Skip to main content
Glama
Sign In
Agnes Media MCP Server

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.

Inputs: prompt (required), size, ratio, image_urls, +1 more.

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.

Inputs: prompt (required), seed, width, height, +6 more.

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.

Inputs: video_id (required), download.

Tool Schema Changelog

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

Loading tool schema changelog…

    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.

    Resources

    Related MCP Connectors

    Related MCP Servers