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.

{
  "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

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

MIT.