# Image Label MCP server

<!-- mcp-name: io.github.sachinbkale27/label-image-mcp -->

An [MCP](https://modelcontextprotocol.io) server for [Image Label](https://labels.sachin-kale.com),
a free image annotation tool. It lets Claude and other AI assistants list and upload your images,
add or clean up annotations, and export COCO or YOLO training data. A LangGraph agent is included.

Use cases and setup guide: https://labels.sachin-kale.com/mcp

```
LangGraph agent (label-image-agent)      Claude Desktop / Claude Code / any MCP client
              │  langchain-mcp-adapters             │
              └──────────────┬──────────────────────┘
                             ▼
                    label-image-mcp (stdio or HTTP)
                             │
                             ▼
                 Image Label API  (/api/images ...)
```

## Account

Uploading and saving annotations needs an Image Label account
([request one](https://labels.sachin-kale.com/contact)). Without one, the tools can read but not
save. Only images saved to your account are visible. Work kept only in your browser is not.

## Install

**Claude Desktop:** download `label-image-mcp.mcpb` from the
[latest release](https://github.com/sachinbkale27/label-image-mcp/releases/latest), open it, and
enter your username and password when asked.

**Claude Code:**

```bash
claude mcp add label-image -e LABEL_USERNAME=... -e LABEL_PASSWORD=... -- uvx label-image-mcp
```

**Any MCP client** (needs [uv](https://docs.astral.sh/uv/)):

```json
{
  "mcpServers": {
    "label-image": {
      "command": "uvx",
      "args": ["label-image-mcp"],
      "env": { "LABEL_USERNAME": "...", "LABEL_PASSWORD": "..." }
    }
  }
}
```

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `LABEL_USERNAME` / `LABEL_PASSWORD` | unset | Account credentials. Without them requests are anonymous and read-only in practice |
| `LABEL_API_URL` | `https://labels.sachin-kale.com/api` | API base URL, for another deployment or `sam local start-api` |

## Tools

| Tool | What it does |
|---|---|
| `list_images(category?)` | Image summaries with annotation counts |
| `get_image(image_id)` | Metadata, annotations and a signed viewing URL |
| `update_image_metadata(image_id, name?, category?, sub_category?, description?)` | Edit image details |
| `add_annotations(image_id, annotations)` | Append pins, polygons, circles, rectangles or arrows |
| `replace_annotations(image_id, annotations)` | Replace all annotations |
| `remove_annotations(image_id, annotation_ids)` | Remove annotations by id |
| `upload_image(path, name?, category?, description?)` | Upload a local image file |
| `export_annotations(image_id, format)` | COCO JSON or YOLO, same output as the web app's export |

There is deliberately no tool for deleting images.

## HTTP mode

`label-image-mcp --http [--host 127.0.0.1] [--port 8765]` serves Streamable HTTP at
`http://HOST:PORT/mcp`, so several clients can share one running server:

```bash
claude mcp add --transport http label-image http://127.0.0.1:8765/mcp
```

## LangGraph agent

A terminal chat agent that uses these tools. The graph is `START → agent ⇄ tools`, with
conversation memory kept for the session.

```bash
uv tool install "label-image-mcp[agent]"
export ANTHROPIC_API_KEY=... LABEL_USERNAME=... LABEL_PASSWORD=...
label-image-agent
```

| Variable | Default | Purpose |
|---|---|---|
| `LABEL_AGENT_MODEL` | `anthropic:claude-sonnet-5-5` | Model as `provider:model`, e.g. `openai:gpt-4.1` or `ollama:llama3.1` (install `langchain-openai` / `langchain-ollama`) |
| `LABEL_MCP_URL` | unset | Connect to a running HTTP server instead of starting one |

## Development

```bash
uv sync --extra agent
uv run pytest
npx @modelcontextprotocol/inspector uv run label-image-mcp
```

In the Image Label app repo, `./start.sh` runs this server in HTTP mode next to the web app.
It reads credentials from `mcp-server/.env`. Releases are described in [PUBLISHING.md](PUBLISHING.md).

## License

MIT