# agnes-image-mcp

Give any MCP client **image generation** and **image understanding** with one API key.

The point is not "another image MCP". The point is that a **text-only model
gains eyes and hands**. Pair a cheap text model (DeepSeek, Qwen, a local
model — anything without vision) with this server and it can suddenly read
screenshots, describe photos, and draw.

Free tier available, no credit card.

## Tools

| Tool | What it does |
|---|---|
| `generate_image` | Text → image. Optional reference images. Returns the image **into the conversation**, and saves a png. |
| `describe_image` | Image(s) + a question → an answer. Screenshots, photos, charts, comparing two images. |
| `set_api_key` | Paste your key in chat and it's saved. Verified against the API first, so a typo fails immediately. |
| `list_models` | What's available on your key, and which model each tool picked. |

Model IDs are resolved **live** on every call — when Agnes ships a newer
generation, this server picks it up with no update needed.

## Setup

Add the server to your client's MCP config. **You do not need to put your key
here** — see step 3.

```json
{
  "mcpServers": {
    "agnes-image": {
      "command": "uvx",
      "args": ["--from",
               "git+https://github.com/hskelp9527-pixel/agnes-image-mcp",
               "agnes-image-mcp"]
    }
  }
}
```

**Do not clone this repo.** `uvx` fetches and builds it into its own cache;
there is no checkout for you to maintain. Copy the block above as-is.

> Not on PyPI yet, so plain `uvx agnes-image-mcp` **will fail** — use the
> `--from git+...` form above. Once the package is published the short form
> starts working and this note goes away.

1. Get a free key at <https://agnes-ai.com>, or <https://platform.agnes-ai.cn>
   if you are in mainland China.
2. Restart your client.
3. Say in chat: **"my Agnes key is sk-..."**

That's it. The agent calls `set_api_key`, which does the rest of the install
for you: verifies the key, generates one small test image, reads it back to
confirm vision works, saves the key, and reports:

```
Key verified against https://apihub.agnes-ai.com/v1 — 7 models reachable.
Image generation: OK (agnes-image-2.1-flash).
Image understanding: OK — it read back 'Red circle shape.'
Key saved to ~/.agnes-image-mcp-key.

Setup complete — image generation and image understanding are both live. Go try it!
已经接通了识图和生图能力，快来试试吧
```

A wrong key fails at step 3, not on your first real image. Nothing else to
configure. If you'd rather not paste a key into a chat window, put
`"env": { "AGNES_API_KEY": "sk-..." }` in the config block instead; the
environment variable takes priority over the saved one.

Works in Claude Desktop, Claude Code, Cursor, Codex, Cline, WorkBuddy, or any
MCP client. On Windows, if `uvx` isn't found, put `"command": "cmd"` and prepend
`"/c", "uvx"` to the args — Windows has no `uvx.exe` for a process spawn to find.

No account, no telemetry, no proxy. The key is stored at
`~/.agnes-image-mcp-key` on your own machine and is sent only to Agnes.

### Two endpoints, picked for you

Agnes runs a global service and a separate mainland-China one, and a key works
on **exactly one** of them:

| Sign-up site | API endpoint |
|---|---|
| agnes-ai.com | `https://apihub.agnes-ai.com/v1` |
| platform.agnes-ai.cn | `https://api.agnes-ai.cn/v1` |

Nobody has to choose. `set_api_key` tries both, keeps whichever accepts the
key, and saves it on line 2 of the key file — later calls go straight there
with no extra request. Set `AGNES_BASE_URL` in the config's `env` block to
force a specific endpoint (or a self-hosted proxy); it overrides everything.

## The one thing worth reading

**How many reference images you pass decides whether the model listens to you.**
This matters more than how you word the prompt. Measured, not guessed:

| refs | keeps the character's look | obeys pose/composition | obeys art style |
|---|---|---|---|
| **0** | only what you describe in words | yes | **yes, exactly** |
| **1** | **yes** | yes | no — style follows the reference |
| **3+** | it's a photocopy | **no** | no — copies props and artifacts too |

Style control and likeness control **cannot both be had in one call**. Pick one:

- Want a specific art style → pass **no** references, describe the character in words.
- Want the same character in a new pose → pass **exactly one** reference, and accept its style.
- Want both → generate once with 0 refs to lock the style, then use that output as the single reference.

Hard cap is 6; more returns HTTP 400. The tool description says all of this too,
so the model applies it without you repeating it every time.

## Limits, stated plainly

- **No SLA.** Agnes's free tier exists to collect usage data. Roughly 20 RPM, and the terms can change without notice. Don't build anything load-bearing on it.
- **Errors are not retried.** If you hit a rate limit you get the error, not a silent backoff. That is deliberate — a hidden retry loop makes a rate limit look like slowness.
- **Generation takes 15–45s** per image. Reference images push it toward the high end.
- **No video, on purpose.** The Agnes key can reach `agnes-video-v2.0` and a
  `generate_video` tool was written and worked on `apihub.agnes-ai.com`. It is
  not shipped because on `api.agnes-ai.cn` the job completes but the finished
  file cannot be fetched: `/videos/{id}/content` answers HTTP 200 with
  `Content-Type: video/mp4` and a 22-byte `{"detail":"Not Found"}` body. The
  gateway blanks `model_id` in the video id it returns, so the download never
  resolves upstream. A capability that only works for half the users is worse
  than no capability. Reachable from git history if that endpoint gets fixed.
- **Not maintained.** This is shared as-is under MIT. Issues and PRs may sit. Fork it — it is one file, ~300 lines, and you will not need help understanding it.

## Development

```bash
pip install -e .
python -m agnes_image_mcp --selftest   # no key needed: checks JSON-RPC handshake + tool schemas
```

MIT.