Agnes Media MCP

English

基于 FastMCP 的 Agnes 图像与视频生成 MCP 服务器（国内版）。

国内版 / 国际版说明： 国内版与国际版的调用方式基本一致，本文档以国内版（api.agnes-ai.cn）为例。如需使用国际版，只需将 Base URL 中的 .cn 改为 .com（即 https://api.agnes-ai.com/v1），其余参数和用法完全相同。

本服务通过环境变量读取凭据，请勿将真实 API Key 放入版本控制文件。

这是什么？

本项目由两部分组成，配套使用：

组件	文件	作用
MCP Server	src/agnes_media_mcp/	执行层——接收工具调用，请求 Agnes API，保存生成结果
Skill	SKILL.md	决策层——告诉 AI Agent 何时激活、选哪个工具、如何构造 Prompt、如何展示结果

简单说：Skill 是大脑，MCP 是双手。只装 MCP 不装 Skill，Agent 不知道何时该调用这些工具；只装 Skill 不装 MCP，Agent 知道该做什么但没有工具可用。

工作流程

<a href="docs/workflow.svg" target="_blank"> <img src="docs/workflow.svg" alt="Agnes Media MCP 工作流程" width="480" /> </a>

流程概览：

用户请求 ─→ [② 包含 "agnes"?] ─否─→ 不激活，交给其他工具
                    │是
                    ▼
         ③ 意图匹配 (Skill: When to Use)
                    │
                    ▼
         ④ 决策规则 → 选择工具
          ├─ 标准图像 → agnes_image_generate
          ├─ 高分辨率 → agnes_image_generate_v2 (1K-4K + ratio)
          ├─ 图像编辑 → agnes_image_edit
          └─ 视频     → agnes_video_generate / submit+wait
                    │
                    ▼
         ⑤ 构造 Prompt (Skill 指南)
                    │
                    ▼
         ⑥ MCP Server 处理 (payload / Base64 / 8n+1)
                    │
                    ▼
         ⑦ Agnes API (api.agnes-ai.cn/v1)
          ├─ 图像: 同步返回 b64_json / url
          └─ 视频: video_id → 轮询 GET /agnesapi
                    │
                    ▼
         ⑧ 保存文件 → outputs/images/ | outputs/videos/
                    │
                    ▼
         ⑨ Agent 展示结果 (Markdown / 路径 / URL)
                    │
                    ▼
         ⑩ 用户获得媒体文件

Skill 层（②③④⑤⑨）负责触发判断、工具选择、Prompt 构造和结果展示；MCP 层（⑥⑧）负责协议适配；API 层（⑦）负责实际推理。

工具列表

工具名	说明
agnes_image_generate	文生图 / 图生图（agnes-image-2.0-flash），精确像素尺寸
agnes_image_generate_v2	高信息密度图像生成（agnes-image-2.1-flash），分级尺寸 1K–4K + 宽高比
agnes_image_edit	图像编辑 / 多图合成，通过 extra_body.image 传入参考图
agnes_video_submit	提交视频生成任务（POST /videos），返回 video_id
agnes_video_status	查询视频任务状态（GET /agnesapi?video_id=<VIDEO_ID>）
agnes_video_wait	轮询任务直至完成、失败或超时
agnes_video_generate	提交视频任务并等待完成（submit + wait 组合）

完整安装配置指南

前提：已安装 uv（一行脚本即可安装，支持 Windows / macOS / Linux）。

第一步：安装 Skill

Skill 是一个 Markdown 文件，告诉 AI Agent 如何智能地使用本工具。将 SKILL.md 复制到你的 Agent 的 Skills 目录：

Hermes：

# 克隆仓库（或仅下载 SKILL.md）
git clone https://github.com/Ryderey/agnes-mcp-studio

# 复制 Skill 到 Hermes skills 目录
cp agnes-mcp-studio/SKILL.md ~/.hermes/skills/agnes-media-generation.md

Qoder / Cursor / 其他支持 Skill 的客户端：

将 SKILL.md 复制到对应的 Skills/Plugins 目录，或通过客户端的「安装 Skill」功能导入。

第二步：配置 MCP Server

在你的 Agent 配置文件中添加 MCP 服务器。

通用 JSON 格式（Claude Desktop / Cursor / Qoder）：

{
  "mcpServers": {
    "agnes_media": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Ryderey/agnes-mcp-studio",
        "agnes-media-mcp"
      ],
      "env": {
        "AGNES_API_KEY": "your_agnes_api_key_here"
      }
    }
  }
}

Hermes YAML 格式：

mcp_servers:
  agnes_media:
    command: "uvx"
    args:
      - "--from"
      - "git+https://github.com/Ryderey/agnes-mcp-studio"
      - "agnes-media-mcp"
    env:
      AGNES_API_KEY: "your_agnes_api_key_here"
      AGNES_OUTPUT_DIR: "/absolute/path/to/outputs"
    timeout: 600
    connect_timeout: 60

第三步：获取 API Key

1. 登录 Agnes AI 控制台
2. 进入 API Key 管理页面，创建并复制 Key
3. 将 Key 填入上一步配置中的 AGNES_API_KEY

第四步：验证

重启 Agent 后，确认 MCP 服务已连接：

# Hermes
hermes mcp list
hermes mcp test agnes_media

其他客户端通常在设置界面可查看 MCP 连接状态。

可选：本地开发模式

如果你想修改源码或调试：

git clone https://github.com/Ryderey/agnes-mcp-studio
cd agnes-mcp-studio
uv sync
cp .env.example .env   # 编辑 .env 填入 API Key
uv run agnes-media-mcp

使用示例

安装配置完成后，在对话中提及 agnes 关键词即可触发。以下是实际对话示例：

生成图像

你： 用 agnes 生成一张赛博朋克城市夜景，16:9 壁纸，2K 分辨率

Agent： 调用 agnes_image_generate_v2（size=2K, ratio=16:9）→ 返回图片文件

你获得： 一张 2624×1472 的图像，保存在 outputs/images/ 目录

编辑图像

你： 用 agnes 把这张照片的背景换成星空，保持人物不变 [附图]

Agent： 调用 agnes_image_edit（image_paths=[你的图片], prompt=...）→ 返回编辑后的图片

生成视频

你： 用 agnes 做一个 5 秒的视频：一只猫在窗台上打盹，阳光慢慢移动

Agent： 调用 agnes_video_generate（duration=5, resolution=720p）→ 等待 30s~3min → 返回视频文件

你获得： 一个 MP4 文件，保存在 outputs/videos/ 目录

触发规则

你说的话	是否触发
“用 agnes 画一只猫”	✅ 触发（包含 agnes + 图像生成意图）
“帮我生成一张图片”	❌ 不触发（未提及 agnes）
“agnes 是什么？”	❌ 不触发（无生成意图）
“AGNES generate a wallpaper”	✅ 触发（不区分大小写）

开发者参考

本地验证

uv run python -c "from agnes_media_mcp.server import mcp; print('import ok')"
uv run python -m pytest tests/ -v
uv run fastmcp inspect src/agnes_media_mcp/server.py:mcp
uv run fastmcp list src/agnes_media_mcp/server.py --json

Python API 直接调用

以下为无需通过 Agent 的编程调用示例：

from agnes_media_mcp.server import agnes_image_generate, agnes_image_generate_v2, agnes_video_generate

# 标准图像生成
result = agnes_image_generate(
    prompt="一只陶瓷咖啡杯放在钢制桌面上，柔和光线",
    size="1024x1024",
)

# 高分辨率图像生成
result = agnes_image_generate_v2(
    prompt="赛博朋克城市夜景，霓虹灯反射，电影质感",
    size="2K",
    ratio="16:9",
)

# 视频生成
result = agnes_video_generate(
    prompt="缓慢推进镜头，玻璃雕塑在画廊中旋转",
    duration=5,
    resolution="720p",
    aspect_ratio="16:9",
)

agnes_video_wait 和 agnes_video_generate 可能运行数分钟，测试时建议使用较短超时。

文档

详细 API 文档请参阅 docs/ 目录：

• 图像 API 文档
• 视频 API 文档
• 配置指南

注意事项

• Base URL 使用国内端点：https://api.agnes-ai.cn/v1
• response_format 必须放在 extra_body 内，不可置于请求体顶层
• 图生图不使用 tags: ["img2img"]，参考图通过 extra_body.image 传入
• agnes_image_generate_v2 使用 agnes-image-2.1-flash，支持 1K–4K 分级尺寸 + ratio 宽高比
• 视频 num_frames 自动对齐 8n+1 规则（上限 441）
• 视频状态轮询使用 video_id，端点为 GET /agnesapi?video_id=<VIDEO_ID>
• 视频结果 URL 从响应的 metadata.url 字段提取
• mask_path 参数会返回结构化不支持错误（当前文档未描述 mask 功能）
• 超时响应包含 video_id 和 last_response，可稍后继续轮询

许可证

MIT License