This server provides Agnes AI image generation and local/remote image utility tools via MCP.
generate_image: Create one image from a text prompt (or reference images) with configurable size, ratio, model, and output as URL or base64.
generate_images: Batch-generate 1–10 images sequentially, with optional per-item IDs and continue-on-error behavior.
download_image: Safely download an HTTPS image to a relative path under the current working directory, with size limits and protections against unsafe URLs, internal addresses, path traversal, and overwrites.
validate_image: Validate a local image file's size and format (PNG, JPEG, GIF, WebP) without network access or file modification.
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 sunset over the ocean"
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.
语言：English · 简体中文
agnes-image-mcp is a Model Context Protocol (MCP) stdio server that exposes Agnes image generation and local image utilities to MCP-compatible clients. It is distributed as an npm package and requires Node.js 20 or newer.
The package is published on npm as agnes-image-mcp. Use @latest for the current stable release, or pin a published version for reproducible deployments.
Install the latest published version globally:
npm install --global agnes-image-mcp@latest
AGNES_API_KEY=your-key agnes-image-mcpRun without a global install:
AGNES_API_KEY=your-key npx --yes agnes-image-mcp@latestFor reproducible deployments, pin the version explicitly:
AGNES_API_KEY=your-key npx --yes agnes-image-mcp@0.1.7The package is an MCP stdio server. It does not open an HTTP listener and does not make an API request until an MCP tool is called.
Related MCP server: image_studio_mcp
Required environment variable:
AGNES_API_KEY: Agnes API credential. Keep it in the environment or a secret manager; never put it in source code or an MCP JSON file committed to version control.
Optional environment variable:
AGNES_MODEL: default model name. If omitted, the server uses agnes-image-2.5-flash.
The repository includes .env.example as a reference. The server reads environment variables supplied by its parent process; it does not automatically load a .env file.
Add a server entry to the MCP client configuration format supported by your client. The following JSON uses the common mcpServers shape:
{
"mcpServers": {
"agnes-image": {
"command": "npx",
"args": ["--yes", "agnes-image-mcp@latest"],
"env": {
"AGNES_API_KEY": "${AGNES_API_KEY}",
"AGNES_MODEL": "agnes-image-2.5-flash"
}
}
}
}If your client does not expand ${AGNES_API_KEY}, replace it at runtime through the client's secret/environment-variable mechanism. For a global install, use "command": "agnes-image-mcp" and omit the package argument.
Bash (Linux/macOS, current shell only):
export AGNES_API_KEY='your-key'
export AGNES_MODEL='agnes-image-2.5-flash' # optional
npx --yes agnes-image-mcp@0.1.7PowerShell (Windows, current session only):
$env:AGNES_API_KEY = 'your-key'
$env:AGNES_MODEL = 'agnes-image-2.5-flash' # optional
npx --yes agnes-image-mcp@0.1.7All tool calls return a structured envelope with code, message, and data fields. Errors are returned as MCP tool errors with a stable error code and do not expose the API key.
generate_imageGenerates one image through the Agnes API. Required inputs are prompt and size; optional inputs include model, ratio, images (reference image strings), and output (url or base64, default url). This is a remote, billable/network operation subject to provider availability and configured rate limiting.
generate_imagesProcesses 1–10 generation items sequentially (concurrency is currently fixed at 1). Each item accepts the same generation fields as generate_image; an optional id labels results. continueOnError defaults to false and controls whether later items run after a failure.
download_imageDownloads an image from an HTTPS URL to a relative path beneath the current working directory. It rejects non-HTTPS URLs, private/internal network targets, path traversal, overwriting existing files, unsupported content, and responses over maxBytes (10 MiB by default). This tool writes a local file and performs network I/O.
validate_imageReads a relative local path beneath the current working directory and validates file size and image signature. PNG, JPEG, GIF, and WebP are supported. It does not access the network or modify the file.
Treat AGNES_API_KEY as a secret. Do not paste it into prompts, logs, issue reports, or checked-in configuration.
The server only performs remote generation when requested by an MCP client. validate_image is local-only.
Download destinations are constrained to the current working directory, and download URL checks reject insecure schemes and private network access.
Image data supplied to generation is sent to the configured Agnes endpoint. Do not send confidential images unless your usage and provider policy allow it.
This package provides image capabilities only; it does not create stories, TTS, subtitles, videos, project files, or persistent databases.
npm install
npm run typecheck
npm test
npm run build
npm pack --dry-runnpm pack --dry-run runs the prepack hook, builds dist/, and previews the exact package contents without publishing. The package allowlist contains dist, README.md, LICENSE, and CHANGELOG.md; npm also always includes package.json. Source, tests, secrets, and node_modules are excluded.
MIT. See LICENSE.
从经过安全校验的 HTTPS 公网地址下载图片到当前工作目录下的相对路径；拒绝内网地址、路径越界、链接和覆盖已有文件。
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| maxBytes | No | ||
| outputPath | Yes |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| data | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses concrete safety behaviors: it rejects intranet addresses, path traversal, links/symlinks, and existing-file overwrites. These details meaningfully shape how an agent can expect the tool to behave.
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?
A single, well-structured sentence with no filler. The primary action is stated first, followed by a clear semicolon-separated list of rejection conditions.
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 description covers the core behavior, security constraints, and path semantics well, and an output schema exists to document return values. The only notable omission is behavior related to maxBytes, which is less critical because the parameter schema provides defaults and bounds.
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%, and the description partially compensates by clarifying that url must be a public HTTPS address and outputPath is a relative path. It does not explain maxBytes or what happens when the limit is exceeded, though the schema's default and maximum provide partial guidance.
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 names a specific verb ('download') and resource ('image') and precisely defines the target location as a relative path under the current working directory. It also distances itself from siblings by focusing on fetching an existing image rather than generating or validating one.
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?
It gives clear context: use it only for HTTPS public addresses and relative output paths, and it lists rejected inputs such as intranet addresses and path traversal. It does not explicitly name sibling alternatives as choices, but the download-vs-generate/validate distinction is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
使用 Agnes 模型生成一张图片。支持文生图或参考图输入，可返回图片 URL 或 base64；会调用远程 Agnes API。
| Name | Required | Description | Default |
|---|---|---|---|
| size | Yes | ||
| model | No | ||
| ratio | No | ||
| images | No | ||
| output | No | url | |
| prompt | Yes |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| data | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent operation, and the description adds useful behavioral context: it calls a remote Agnes API and supports both URL and base64 output. It does not contradict any annotation, though it could mention side effects like cost or latency.
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?
Two compact sentences with no filler. The main action and model are front-loaded, and the supporting capabilities are listed efficiently.
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 description covers the core use case and remote API dependency, and an output schema exists to define return values. Still, with six parameters and no schema-level descriptions, the description leaves gaps around image input format, size meaning, and model choices, making it slightly incomplete for fully confident invocation.
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 compensate. It partially does by implying prompt for text-to-image, images for reference input, and output for URL/base64. However, it does not clarify size, ratio, or model semantics, leaving the agent to infer from enums and names.
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 states a clear verb and resource: '使用 Agnes 模型生成一张图片' (generate an image with the Agnes model), and adds concrete behavior: text-to-image or reference-image input, returning URL or base64. The singular '一张图片' also helps distinguish from the sibling generate_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 explains what the tool can do but gives no guidance on when to choose it over siblings like generate_images, download_image, or validate_image. There is no mention of when not to use it, prerequisites, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按顺序批量调用 Agnes 生成图片，默认遇错停止；可选择继续处理并返回每项成功、失败和跳过统计。
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| concurrency | No | ||
| continueOnError | No |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| data | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
描述补充了注释未覆盖的关键行为：按顺序执行、默认遇错停止、可配置继续处理并返回成功/失败/跳过统计。这些信息对调用方非常重要，且与 openWorldHint=true 等注释一致，无矛盾。
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?
描述为单句话，信息密度高且无冗余，先说明核心动作，再补充错误处理与返回统计。虽然紧凑，但结构不算条理化，较长的单句可能稍显拥塞。
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?
输出 schema 已提供返回统计的结构，注释也标记了副作用特性，描述则提供了调用策略（顺序、错误处理）。但 schema 覆盖率 0% 时，描述未能点明 items 参数的基础要求（如每项需 prompt 和 size），调用 agent 仍需完全依赖 schema。
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 描述覆盖率为 0%，描述需要补偿参数含义，但仅间接提到了 continueOnError（'可选择继续处理'），未解释 items 数组的结构、prompt 和 size 要求，也未提及 concurrency 固定为 1。描述几乎没有为参数提供超出 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?
描述使用明确动词'批量调用 Agnes 生成图片'，指明资源与动作，并强调'批量'，与兄弟工具 generate_image 形成清晰区分。读者无需查看其他工具即可理解这是批量生成图片的工具。
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?
描述通过'批量'一词隐含适用于一次生成多张图片的场景，但未明确说明何时应改用 generate_image 或与其他兄弟工具的关系。没有给出 when-not-to-use 或替代工具的指引。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取当前工作目录下的相对路径，校验本地文件大小及 PNG、JPEG、GIF、WebP 格式，不访问网络也不修改文件。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| maxBytes | No |
| Name | Required | Description |
|---|---|---|
| code | Yes | |
| data | Yes | |
| message | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context beyond those: no network access, no file modification, and validation of file size and specific image formats. This gives an agent useful constraints without contradicting the annotations.
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?
A single sentence carries the action, scope, validation criteria, and side-effect exclusions with no filler. All key information is front-loaded and every clause earns its place.
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 output schema covers return-value expectations, and annotations cover safety and idempotency. The description completes the picture with path scoping, format restrictions, and explicit no-network/no-modification guarantees. It is concise but sufficient for a simple validation 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 compensate. It does map the path parameter to a current-working-directory relative path and implies maxBytes through file-size validation, but it does not explicitly name the parameters or explain defaults and bounds. This is adequate but not fully explicit.
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 names a specific action (读取/校验) and resource (local image file), and further scopes it to relative paths in the current working directory plus specific formats (PNG, JPEG, GIF, WebP). It clearly distinguishes itself from siblings like generate_image and download_image, which create or fetch images rather than validating existing local files.
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: local files, relative paths, and explicit statements that it does not access the network or modify files. However, it does not explicitly name sibling alternatives or state when to prefer those instead, so the usage guidance is clear but not fully exclusionary.
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: single generation, batch generation, downloading, and validating images. The singular/plural naming clearly separates generate_image from generate_images, and download/validate do not overlap with generation.
All tool names follow the same verb_noun snake_case pattern: generate_image, generate_images, download_image, validate_image. The pluralization is intentional and consistent with the batch behavior.
Four tools are well-scoped for an image generation server covering creation, batch creation, download, and validation. The count is small enough to avoid overload while providing a complete practical workflow.
The server covers the core image generation workflow: single generation, batch generation, downloading results, and validating local files. Minor gaps exist, such as no explicit image editing or metadata retrieval, but these are not essential to its stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Generate AI images and videos from any compatible MCP client.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
Browse, search, upload, tag, transfer, and delete images in your Raster libraries over MCP.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ybd0612/agnes-image-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
