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 即可拿到文件。

安装与构建

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（图片 / 视频），可放心联调。