Skip to main content
Glama
Ryderey

Agnes Media MCP

by Ryderey
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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 知道该做什么但没有工具可用。

Related MCP server: laozhang-image MCP

工作流程

流程概览：

用户请求 ─→ [② 包含 "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/ 目录：

注意事项

  • 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

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • vicsee-mcp-server

    Generate, edit and upscale AI video and images from any agent via VicSee.

  • Future Video Studio

    Create and manage cinematic AI video renders through the Future Video Studio Agent API.

  • Glif

    Generate images, video, and audio with Glif's media-generation agent

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ryderey/agnes-mcp-studio'

If you have feedback or need assistance with the MCP directory API, please join our Discord server