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

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

Related MCP server: imagegen-mcp

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": ["agnes-image-mcp"]
    }
  }
}

1. Get a free key at https://agnes-ai.com.

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: 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, use "command": "cmd", "args": ["/c", "uvx", "agnes-image-mcp"] — 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.

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:

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.

• Not maintained. This is shared as-is under MIT. Issues and PRs may sit. Fork it — it is one file, ~150 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.