Skip to main content
Glama
peypey84

Agnes Media MCP Server

by peypey84
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Agnes Media MCP Server

一个用于 Claude Desktop 的本地 MCP 服务器，内置：

  • Agnes Image 2.1 Flash (agnes-image-2.1-flash) — 文生图 / 图生图

  • Agnes Video V2.0 (agnes-video-v2.0) — 文生视频 / 图生视频 / 关键帧动画（异步）

接入后，在 Claude Desktop 里用自然语言即可生成图片和视频，结果自动落盘到本地目录。

跨平台：服务器由 Node 运行，macOS 与 Windows 均可使用。

工具

工具

说明

agnes_generate_image

生成图片。默认文生图；传 image_urls 走图生图。结果落盘 + 内嵌预览。

agnes_generate_video

创建视频任务并短等待（默认 45s）。若在等待窗口内完成则直接下载 mp4；否则立即返回 video_id 交给状态工具轮询。默认文生视频；传 image_url 图生视频；传 keyframe_urls 关键帧过渡。

agnes_get_video_status

按 video_id 查询视频任务状态；download:true 在完成时下载 mp4。

视频时长：seconds = num_frames / frame_rate。num_frames 必须 ≤ 441 且满足 8n+1（如 81≈3s、121≈5s、241≈10s、441≈18s @ 24fps）。

为什么视频要两步：视频生成通常需要数分钟，超过单次 MCP 请求的超时（约 60s）。因此 agnes_generate_video 只在客户端超时预算内（wait_seconds，默认 45s、上限 50s）内联等待——快的视频一次返回；慢的立即交回 video_id，用 agnes_get_video_status（download:true）每隔约 15s 轮询直到 completed 即可拿到文件。

Related MCP server: Jimeng MCP Server

安装与构建

npm install
npm run build

生成 dist/index.js。

配置（环境变量）

变量

必填

默认

说明

AGNES_API_KEY

是

—

Agnes AI API Key

AGNES_OUTPUT_DIR

否

系统图片/视频文件夹

覆盖输出根目录（设置后图片→<dir>/images、视频→<dir>/videos）

AGNES_BASE_URL

否

https://apihub.agnes-ai.com

API 网关地址

默认落盘位置：不设 AGNES_OUTPUT_DIR 时，图片保存到系统"图片"文件夹、视频保存到系统"视频"文件夹，各自放在 AgnesOutputs/ 子目录下。Windows 上会读取真实的已知文件夹路径（支持重定向，如 H:\用户文件\图片）；macOS/Linux 回退到 ~/Pictures、~/Videos。

网络重试：所有 API 调用与文件下载都带自动重试（网络失败或 429/5xx 时等 2 秒重试，共 4 次尝试），以应对偶发的网络抖动。

接入 Claude Desktop

编辑 Claude Desktop 配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json(不同版本的路径可能不一样）

加入（把路径换成本机 dist/index.js 的绝对路径）：

{
  "mcpServers": {
    "agnes-media": {
      "command": "node",
      "args": ["/绝对路径/图片和视频MCP/dist/index.js"],
      "env": {
        "AGNES_API_KEY": "你的Key",
        "AGNES_OUTPUT_DIR": "可选自定义输出目录"
      }
    }
  }
}

Windows 下 args 路径示例："C:\\Users\\you\\projects\\图片和视频MCP\\dist\\index.js"（反斜杠需转义，或用正斜杠）。

保存后完全重启 Claude Desktop。连接成功后即可对 Claude 说：“生成一张 16:9 的霓虹灯城市壁纸”。

本地调试

用官方 MCP Inspector 手动调用工具：

AGNES_API_KEY=你的Key npm run inspect

在 Inspector 里：

  1. agnes_generate_image — prompt 任意，size: "2K", ratio: "16:9" → 检查系统「图片」文件夹下 AgnesOutputs/ 出图。

  2. agnes_generate_video — num_frames: 121, frame_rate: 24 → 等待轮询完成，检查系统「视频」文件夹下 AgnesOutputs/ 出 mp4。

  3. agnes_get_video_status — 传上一步的 video_id。

注意事项

  • 日志走 stderr，stdout 专供 MCP 协议，请勿改动。

  • 视频为异步生成，可能需要数分钟；服务器会阻塞轮询（默认间隔 5s、超时 10 分钟）。超时后可用 agnes_get_video_status 继续查询。

  • 图生图不需要 tags；response_format 由服务器自动放进 extra_body。

  • 定价当前为 $0（图片 / 视频），可放心联调。

Available Tools

3 tools
agnes_generate_imageA

Generate an image with Agnes Image 2.1 Flash. Text-to-image by default; pass image_urls to do image-to-image (transform/restyle while preserving composition). The result is saved to the local output directory and a preview is returned inline.

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNoOutput size tier. 1K/2K/3K/4K.2K
ratioNoAspect ratio, e.g. 16:9 for wallpapers.1:1
promptYesWhat to generate, or how to transform the input image(s).
image_urlsNoOptional input images (public URL or data URI) to enable image-to-image.
inline_previewNoAlso return the image inline as a preview (small files only).

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that images are saved locally and a preview is returned inline (only for small files). However, it omits details such as whether the tool is blocking, if it overwrites existing files, any cost or rate limits, and the exact return format beyond a preview.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no extraneous information. The description is front-loaded with the main purpose and is structured logically: mode explanation, then outcome.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the core functionality and modes. However, it lacks details on output file naming, handling of duplicate file names, limitations on prompt length or image_urls count, and the structure of the inline preview response. Given no output schema, more completeness on return values would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the mode switch tied to image_urls and the size limitation for inline_preview. Other parameters (size, ratio, prompt) are not elaborated beyond the schema, so no significant added meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates images using a specific model (Agnes Image 2.1 Flash). It distinguishes between text-to-image and image-to-image modes, and given sibling tools are for video, the tool's purpose is unambiguous and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use each mode: text-to-image by default, image-to-image when image_urls are provided. It does not explicitly state when not to use the tool or provide alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agnes_generate_videoA

Start an Agnes Video V2.0 generation (async). Text-to-video by default; pass image_url for image-to-video, or keyframe_urls (2+) for keyframe transitions. Video generation takes minutes, longer than an MCP request can block. This tool creates the task and waits up to wait_seconds for it to finish: if it completes in time, the mp4 is downloaded locally and its path returned; otherwise it returns the video_id immediately — poll agnes_get_video_status with that id (download:true) to fetch the result when ready. Duration = num_frames / frame_rate. num_frames must be <=441 and of the form 8n+1.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoRandom seed for reproducible results.
widthNoVideo width (default 1152).
heightNoVideo height (default 768).
promptYesText description of the video content / motion.
image_urlNoImage URL for image-to-video.
frame_rateNoFrames per second (1-60).
num_framesNoFrame count (<=441, 8n+1). 81≈3s, 121≈5s, 241≈10s, 441≈18s at 24fps.
wait_secondsNoHow long to wait inline for completion before handing off (0-50s). Kept under the MCP client request timeout; if the video isn't ready, the video_id is returned to poll.
keyframe_urlsNo2+ keyframe image URLs for keyframe-transition mode.
negative_promptNoWhat to avoid in the video.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses async nature, blocking duration (wait_seconds), return behavior (local path vs. video_id), and constraints on num_frames (<=441, 8n+1). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph is functional and every sentence adds value, but could be more structured (e.g., bullet points for modes). Not too long, well-focused.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 10 params and no output schema, description covers async flow, constraints, mode selection, and return values. Lacks explicit error handling details but sufficient for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but description adds significant value: explains mode parameter usage in prose, clarifies wait_seconds logic, and provides frame count examples (81≈3s, etc.) beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it starts async video generation (Agnes V2.0), enumerates three modes (text-to-video, image-to-video, keyframe transitions), and distinguishes from siblings (agnes_get_video_status for polling, agnes_generate_image for images).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when to use each mode, describes wait_seconds inline behavior, and directs polling with agnes_get_video_status upon timeout. Provides clear when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

agnes_get_video_statusA

Check the status of an Agnes video task by video_id. Returns status/progress, and if completed, the remote URL. Optionally downloads the mp4 locally when ready.

ParametersJSON Schema
NameRequiredDescriptionDefault
downloadNoIf completed, download the mp4 to the local output directory.
video_idYesThe video_id returned when the task was created.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses optional download, but lacks details on side effects (e.g., filesystem changes) or error states. No annotations, so description should provide more behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences, front-loaded with purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Explains return values (status, URL) and optional download, but lacks output format details. Adequate for a simple poll tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. Description adds little beyond schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool checks status of a video task, returns progress and URL, and optionally downloads. Distinguishes from sibling generation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context: used after task creation to check status. No explicit exclusions or alternatives, but implied by sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedagnes_generate_image
    • First observedagnes_generate_video
    • First observedagnes_get_video_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: image generation, video generation (async), and video status retrieval. No overlap in purpose.

Naming Consistency5/5

All tools follow a consistent 'agnes_verb_noun' pattern with underscores (e.g., generate_image, get_video_status). No mixing of styles.

Tool Count4/5

3 tools is minimal but appropriate for the focused scope of image and video generation. Could be expanded with list/delete utilities, but not underpowered.

Completeness3/5

Covers core generation and status polling, but lacks list/delete or cancel operations for videos, and no tool for managing images beyond generation.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers