This server gives any MCP client image generation and understanding capabilities using a single Agnes API key. You can generate images from text prompts (with optional reference images for character likeness, customizable size/aspect ratio, saved as PNG), and describe images by asking questions about one or more images (local files or public URLs) to read text from screenshots, compare images, etc. Securely set and verify your API key with end-to-end testing. List available models and see defaults. Key features: free tier, global and China endpoints, local key storage, works across MCP clients like Claude and Cursor.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agnes-image-mcp Generate an image of a futuristic city skyline at night."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | What it does |
| Text → image. Optional reference images. Returns the image into the conversation, and saves a png. |
| Image(s) + a question → an answer. Screenshots, photos, charts, comparing two images. |
| Paste your key in chat and it's saved. Verified against the API first, so a typo fails immediately. |
| 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.
Related MCP server: imagegen-mcp
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-mcpwill fail — use the--from git+...form above. Once the package is published the short form starts working and this note goes away.
Get a free key at https://agnes-ai.com, or https://platform.agnes-ai.cn if you are in mainland China.
Restart your client.
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.
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 |
|
platform.agnes-ai.cn |
|
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.
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.
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.
pip install -e .
python -m agnes_image_mcp --selftest # no key needed: checks JSON-RPC handshake + tool schemasMIT.
Look at one or more images and answer a question about them.
Gives vision to a text-only model. Useful for: reading text in a screenshot, describing a photo, checking whether a generated image matches a brief, comparing two images, extracting data from a chart.
Args: images: local file paths or public https URLs. question: what to ask about them. Be specific — "what error is shown in this screenshot" beats "describe this".
| Name | Required | Description | Default |
|---|---|---|---|
| images | Yes | ||
| question | No | Describe this image in detail. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses accepted input formats (local paths or public https URLs), the ability to handle multiple images, and gives advice on specificity. It does not mention limitations like file size or access restrictions, but the disclosed details are meaningful and go beyond a simple operation statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: a clear one-sentence purpose, a 'Useful for' bullet list, then an Args section. Every sentence adds value, and the example question is practical rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no nested objects) and the description covers purpose, use cases, and parameter semantics. An output schema exists, so not detailing return values is acceptable. The description fully equips an agent to decide when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does: 'images' is explained as local file paths or public https URLs, and 'question' is explained with guidance to be specific, including a concrete example. This adds substantial meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource phrase: 'Look at one or more images and answer a question about them.' It clearly distinguishes from siblings (generate_image creates images; list_models and set_api_key are unrelated) and provides concrete example use cases like reading screenshots and comparing images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: it provides vision to a text-only model and lists several useful scenarios (reading text, describing photos, checking generated images, comparing images, extracting chart data). It does not explicitly name alternatives or state when not to use it, but the context is sufficient given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an image from a text prompt. Returns the image itself.
HOW MANY reference_images you pass decides whether the model obeys you. This matters more than prompt wording:
0 refs -> art style and composition instructions are followed exactly. The look of any character must be described in words. 1 ref -> keeps the referenced character's likeness AND follows pose instructions, BUT the art style will follow the reference, not your prompt. Use for expression sets / same character, new pose. 3+ refs -> the model starts copying instead of creating. Pose and style instructions stop working; it reproduces the reference, including its background props and artifacts. Avoid.
Style control and likeness control cannot both be had in one call. Decide which one this image needs. To get both: generate once with 0 refs to fix the style, then use that output as the single ref for follow-ups.
Hard limit: 6 reference images, more returns HTTP 400.
Args: prompt: what to draw. Put the full art-style description here. reference_images: local file paths or public https URLs. Read the rule above. size: e.g. "1024x1024", or a tier like "1K" / "2K". ratio: e.g. "1:1", "16:9". save_path: where to write the png. Defaults to a temp file; the path is always reported so the user can find the file.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 1024x1024 | |
| ratio | No | 1:1 | |
| prompt | Yes | ||
| save_path | No | ||
| reference_images | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and excels: it reveals how reference image count changes behavior, states a hard limit of 6 images returning HTTP 400, explains that style follows the reference when 1 ref is used, and discloses the default save_path behavior and that the path is always reported. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and organized with clear sections, front-loaded with the core purpose before diving into details. It is somewhat long, but each sentence earns its place by conveying necessary behavioral nuance and parameter guidance. The structure follows a logical flow from purpose to reference-image rules to argument definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, lack of schema descriptions, and absent annotations, this description is remarkably complete. It covers usage, edge cases (3+ refs), error conditions (HTTP 400), return behavior ('returns the image itself' and path reporting), and parameter semantics. It leaves few gaps for an agent to misinterpret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description meticulously explains every parameter: prompt ('full art-style description'), reference_images ('local file paths or public https URLs' plus the critical rule), size with examples ('1024x1024' or '1K'), ratio with examples, and save_path ('where to write the png' and default). It fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Generate an image from a text prompt.' It distinguishes itself from sibling tools like describe_image by specifying it generates rather than analyzes imagery, and the detailed behavior around reference images further clarifies its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use 0, 1, or 3+ reference images, and explains the tradeoff between style and likeness control, including a practical workaround for both. It does not explicitly mention sibling alternatives, but the content strongly implies when this tool is appropriate for image generation tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the models available on this API key, and which ones this server picks by default for generation and for vision.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite having no annotations, the description transparently discloses that the tool reads model availability and default selections. It doesn't mention potential errors or prerequisites (like needing to set an API key), but for a read-only list operation, the behavioral surface is small and the description covers the essential behavior without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that leads with the action 'List' and immediately specifies the resource and additional details about default selections. No redundant words, and the structure places the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema present, the description is fully sufficient. It states exactly what the tool returns: available models and default choices. The provided output schema likely explains the return structure, so no further exposition is needed. The sibling tools don't introduce ambiguity that would require more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so the description doesn't need to explain parameter syntax or meaning. The input schema confirms this, and the guideline for 0 params sets baseline 4. The description adds nothing about parameters because none exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists models available on the API key and notes the server's default picks for generation and vision. It uses a specific verb 'List' and the resource 'models', distinguishing it from siblings that set API keys or generate/describe images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this to discover available models and defaults. However, it gives no explicit guidance on when to use it versus alternatives, nor when not to use it. Given its simple listing nature, the context is reasonably clear, so this is barely adequate rather than poor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set up this server with the user's API key. This is the whole install: save the key, then prove both capabilities actually work end to end.
Call this as soon as the user provides a key. Report the returned message back to them verbatim — it is the completion notice.
The key is verified before being written, so a typo fails here rather than on the first real request. It is stored in plain text at ~/.agnes-image-mcp-key on this machine only, and is sent only to Agnes. AGNES_API_KEY in the environment still wins if set.
Args: key: the Agnes API key, starting with "sk-". Free at https://agnes-ai.com. run_check: generate one small image and read it back to confirm both paths work. Takes 20-60s. Only skip it if the user is in a hurry.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| run_check | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses side effects: key is verified before writing, stored in plain text at a specific path, sent only to Agnes, and the run_check will generate and read back an image. It also notes that typos fail early, providing clear behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but every sentence adds value: security, verification, environment precedence, and verbatim reporting instruction. It is well-organized with an Args section, but could be tightened slightly by merging the 'whole install' sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a setup tool with two parameters and no annotations, the description covers all necessary context: what it does, when to call it, side effects, return handling, and parameter details. The presence of an output schema is not needed because the description tells the agent to relay the message verbatim.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions, and schema coverage is 0%. The description compensates fully by explaining the key format ('sk-'), the free source, and the time cost (20-60s) and purpose of run_check, going far beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Set up this server with the user's API key.' It distinctively describes the installation scope and is clearly differentiated from sibling tools like generate_image and describe_image, which are runtime operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage instruction: 'Call this as soon as the user provides a key.' It also tells when to skip the run_check ('Only skip it if the user is in a hurry'), and clarifies precedence with 'AGNES_API_KEY in the environment still wins if set.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: list_models shows available models, set_api_key configures the API key, generate_image creates images, and describe_image interprets images. There is no functional overlap between any pair.
All tool names follow the same verb_noun pattern in snake_case: list_models, set_api_key, generate_image, describe_image. The naming is perfectly consistent and predictable.
Four tools is a well-scoped count for an image generation and vision server. Each tool covers a necessary step in the workflow from setup to generation to analysis, with no redundant or missing components.
The tool set covers the full lifecycle of the server's purpose: configuration (set_api_key), discovery (list_models), creation (generate_image), and understanding (describe_image). There are no obvious gaps for the intended use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Qwen Image 3 AI image generation
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for NanoBanana AI image generation and editing
MCP server for Flux AI image generation
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hskelp9527-pixel/agnes-image-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server