Skip to content

annotools

Let agents see and annotate multimodal data within a token budget. annotools downscales and crop-zooms images, video frames and audio, draws grid guide lines and BBox / keypoint / polygon / segmentation overlays, and keeps every coordinate in one convention — normalized 0.0–1.0 relative to the uncropped source.

It serves two audiences, both first-class:

  • An MCP server for coding agents

    Register annotools with Claude Code, Codex or OpenCode and the agent can look at a dataset the way you would — a downscaled preview, a zoom into one region, a grid to anchor positions — without blowing its context on full-resolution images.

    Tool reference

  • A library for agent developers

    The same previews, overlays and coordinate conversions as plain Python functions, so a pipeline built on the Claude Agent SDK or the Codex SDK can give its own execution agent eyes. Importing annotools never loads fastmcp.

    API reference

Install

uv add "annotools @ git+https://github.com/hoshiori-dev/annotools"

Add the media extra for video and audio, or run the container (ghcr.io/hoshiori-dev/annotools) — see Install. Then register the server with Claude Code, Codex or OpenCode and set the preview size for the model behind the agent: 384 px keeps a Gemini image at one 258-token unit, while Claude and GPT bill by area and read 768 px comfortably.

Use the library

from annotools import BBoxObject, draw_bboxes, encode, load_image, normalize_coordinates, preview

result = preview(load_image("photo.jpg"), max_width=768, max_height=768)
boxes = normalize_coordinates([[120, 80, 300, 260]], result.metadata["output_width"], result.metadata["output_height"])
overlay = draw_bboxes(result, [BBoxObject(bbox=boxes[0], label="cat")])
image_bytes = encode(overlay.image, "jpeg")

More

  • As an MCP server and As a library — settings, coordinates, and the shape of a call.
  • API reference — every public function, generated from its docstring.
  • MCP tool reference — parameters, return shape and specification of all 13 tools.
  • Architecture — layers and recorded decisions.
  • Recipes — one page per task (captioning, detection, keypoints, polygons, segmentation, video, audio), each as library code and as the MCP call.
  • Cookbook — how an agent-run annotation project gets from an interview to an exported dataset, one page per step.
  • Skills — the annotation methodology as installable agent skills: npx skills add hoshiori-dev/annotools.
  • Examples — four complete pipelines (image captioning and object detection, on the Claude Agent SDK and the Codex SDK).