agnes-2.5-flash-mcp
This server integrates Agnes AI's 2.5-flash image and video generation models into MCP-compatible IDEs, letting you generate and edit images and create videos via natural language.
Image generation/editing (
generate_image): text-to-image, image-to-image, and multi-image composition; supports sizes 1K–4K, multiple aspect ratios, URL or base64 output, optional local saving.Async video creation (
create_video): starts a non-blocking video generation task and returns avideo_idto avoid client timeouts.Video progress polling (
query_video): checks status/progress of a video task and returns the video URL when complete.Synchronous video fallback (
generate_video): blocking video generation for short clips, with configurable polling and timeout; reusesvideo_idon timeout.Video modes: text-to-video, keyframe (first/last frame) and reference-based video (images/audios); fixed 720P, 4–12 second durations, and multiple aspect ratios.
Flexible API key configuration: tool arguments, MCP env var, system env, or
.env; supports custombase_url.Plays well with agentic IDEs: uses MCP stdio, designed for Opencode, Claude Desktop, Cursor, Windsurf, etc.; includes built-in parameter validation and bilingual trigger descriptions for reliable routing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agnes-2.5-flash-mcp Generate an image of a cozy cabin in snowy mountains"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agnes 2.5 Flash MCP Server 🚀
🌟 工程亮点 (致面试官)
虽然 Agnes 提供了非常优秀的免费图像和视频生成模型(agnes-image-2.5-flash / agnes-video-2.5-flash),但开发者在 IDE 和网页之间频繁切换上下文非常打断心流。最初,这只是为了在 Opencode 中免去切网页烦恼而写的自用工具,现已正式发布至 PyPI,任何开发者均可直接安装,将 AI 生成能力一键接入自己的 Agentic IDE(如 Opencode、Claude Desktop、Windsurf 等)。
核心技术决策与实现:
彻底解决客户端超时痛点 (Robust Async Workflow):由于视频生成通常耗时数分钟,极易导致 Opencode/Claude 等 MCP 客户端的标准请求超时。为此,我设计了异步的任务轮询系统 (
create_video→query_video),允许 Agent 非阻塞地检查进度,保证了长耗时任务的稳定性。前置强校验与防御性编程 (Strict Parameter Validation):在本地层面对请求参数进行 Flash 强校验(例如:强制
720P分辨率,校验图文音附件数量等)。这能将无效请求在发起网络调用前瞬间拦截,既降低了网络延迟,又避免了无意义的 API 额度消耗。自然语言无缝路由 (Intelligent Intent Routing):在工具描述(Description)设计中,深度优化了中英双语的触发词(如“生一张图”、“draw a cyberpunk city”)。LLM 能够根据上下文自动推断用户意图,精准路由到正确的工具函数,完全免去了繁杂的 Prompt 设定。
标准化与兼容性 (Plug-and-Play Design):完全遵循官方的 MCP
stdio传输层规范,实现即插即用,兼容市面上绝大多数支持 MCP 的智能客户端。
Related MCP server: Image Gen MCP
🚀 支持的模型与端点
注意: 本项目为 2.5-flash 专版。如果您需要 2.0/2.1 或
agnes-video-v2.0的支持,请使用社区版的agnes-mcp。
图像生成:
agnes-image-2.5-flash模型(接口:POST /v1/images/generations)视频生成:
agnes-video-2.5-flash模型(接口:POST /v1/videos&GET /agnesapi,尺寸固定为720P)
📦 安装说明
# 通过 pip 安装
pip install agnes-2.5-flash-mcp
# 或从源码安装
git clone https://github.com/JasonOracle/agnes-2.5-flash-mcp.git
cd agnes-2.5-flash-mcp
pip install -e .要求 Python ≥ 3.10.
🔑 配置说明 (API Key)
API Key 解析优先级:
工具调用参数 > MCP 环境变量 AGNES_API_KEY > 系统环境变量 > .env 文件。
推荐方式: 直接在您的 MCP 客户端配置中设置,避免将 Key 提交到代码库。
{
"mcpServers": {
"agnes-2.5-flash-mcp": {
"command": "agnes-2.5-flash-mcp",
"args": [],
"env": {
"AGNES_API_KEY": "您的_API_KEY"
}
}
}
}代理配置: 如果
ALL_PROXY=socks5://...导致httpx报错,请将ALL_PROXY留空,或使用 HTTP 代理HTTP_PROXY=http://127.0.0.1:10808。或者安装 socks 支持:pip install "httpx[socks]"。
🔌 IDE 接入指引
Cursor / Claude Desktop
将以下内容添加到您的 .cursor/mcp.json 或 claude_desktop_config.json 中:
{
"mcpServers": {
"agnes-2.5-flash-mcp": {
"command": "agnes-2.5-flash-mcp",
"env": { "AGNES_API_KEY": "YOUR_KEY" }
}
}
}(如果不使用 pip 安装:请使用 command: "python", args: ["-m", "agnes_2_5_flash_mcp.server"], 并指定 cwd 目录)
Opencode
请参考项目中的 opencode.json.example 文件。
🛠️ 工具参考 (Tools)
工具名称 | 功能描述 | 返回格式 |
| 文生图、图生图、图像合成。(返回 URL,可选保存至本地) |
|
| (推荐) 异步创建视频生成任务。 |
|
| 根据 |
|
| (兼容) 同步阻塞式生成(仅限短视频,可能触发超时)。 |
|
🖼️ 图像约束 (默认:2K + 16:9)
分辨率 (Size):
1K(快速) /2K(默认, ≈ 2624x1472) /3K/4K(最大)比例 (Ratio):
16:9/1:1/9:16/3:4/4:3/2:3/3:2/21:9能力: 传入
images参数(URL 或 Data URI)可进行图生图/图像合成,省略则为纯文生图。
🎥 视频约束 (本地强校验)
尺寸 (Size): 固定为
720P。时长 (Duration):
"4"至"12"秒(默认"5")。比例 (Ratio):
16:9(默认) /21:9/4:3/1:1/3:4/9:16。校验: 采用严格校验逻辑(如:文本模式禁止包含媒体附件,关键帧模式首尾帧必须 ≥ 1 等)。
💬 使用示例 (直接对 Agent 说)
"用
generate_image生成一张 2K 16:9 的赛博朋克城市夜景壁纸。""把这张图 (URL) 改成雨夜霓虹风格,保持构图,尺寸用 2K。"
"用
create_video生成 5 秒 16:9 的未来城市街道视频,然后用query_video帮我轮询结果。"
🧪 本地测试
测试套件 (tests/test_validation.py) 是纯本地校验测试,不会产生任何 API 调用计费。
python -m pytest tests -qAvailable Tools
4 toolscreate_videoA
Create an async agnes-video-2.5-flash task (RECOMMENDED). Returns video_id; poll with query_video.
中文触发:当用户说「生视频 / 生成视频 / 做个视频 / 图生视频 / 首尾帧 / 参考图视频」时优先调用此工具(异步默认,避免IDE超时)。 Trigger: agnes generate video (async) / text-to-video / image-to-video / keyframe.
mode text: pure text (no media). keyframe: first_frame and/or last_frame required. reference: images (<=5) and/or audios (<=3) required; use / in prompt. size is fixed 720P. seconds is a string "4".."12" (default "5").
Examples:
纯文本生视频:prompt="未来城市街道", mode="text", seconds="5"
首尾帧:prompt="街道由白天变为夜晚", mode="keyframe", first_frame="https://.../a.png"
Inputs: prompt (required), mode, seed, audios, +7 more.
generate_imageA
Generate or edit an image with agnes-image-2.5-flash. Always returns a URL (or base64).
中文触发:当用户说「agnes生图 / 生成图片 / 做张图 / 文生图 / 图生图 / 改图 / 多图合成」时调用此工具。 Trigger: agnes generate image / text-to-image / image-to-image / edit image.
Presets: size 1K(fast/cheap) / 2K(default, wallpaper 16:9=2624x1472) / 3K / 4K(max quality).
ratio 16:9 default (wallpaper), 1:1 social, 9:16 vertical, 21:9 ultrawide.
Pass images (public URL or Data URI) for image-to-image / multi-image compose;
omit it for pure text-to-image. save_path is optional: when given, the result
is also downloaded locally.
Examples:
纯文生图:prompt="赛博朋克夜景壁纸", size="2K", ratio="16:9"
带图改图:prompt="改成雨夜霓虹风格,保持构图", images=["https://.../a.png"]
Inputs: prompt (required), size, ratio, images, +4 more.
generate_videoA
Create a video task and block-poll until completed/failed (compat; may hit client timeouts).
⚠️ 同步阻塞(易超时):开源推荐用 create_video + query_video;此工具仅为短视频兼容保留。 中文触发:仅当用户明确说「一步到位 / 直接等视频结果」时才用,否则用 create_video。 Trigger (compat): agnes generate video sync; prefer async create_video + query_video.
Same params as create_video plus poll_interval (default 2s) and timeout_seconds (default 600s). On timeout, reuse video_id with query_video.
Inputs: prompt (required), mode, seed, audios, +9 more.
query_videoA
Query an agnes-video-2.5-flash task. Returns status/progress and video_url when completed.
中文触发:视频创建后,用此工具按 video_id 轮询进度(配合 create_video 使用)。
Inputs: video_id (required), api_key, base_url.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
query_video and generate_image are clearly distinct, but create_video and generate_video describe the same core operation with different execution modes. The descriptions help differentiate them, but an agent could still easily pick the wrong one.
All names follow a snake_case verb_noun pattern, but the verbs are inconsistent: query, generate, create, generate. The create_video vs generate_video pair is especially confusing since they are near-synonyms for the same capability.
Four tools is a reasonable size for an image/video generation server. The only slight issue is that generate_video is a redundant sync variant of create_video, but it serves a compatibility purpose.
The core image generation and video creation lifecycles are covered: generate image, create video asynchronously, query status, and sync wait. Minor gaps like cancellation or image task polling are not blocking for the apparent domain.
Maintenance
Related MCP Connectors
Generate AI video, images and audio, and browse your history, from any MCP client.
Generate AI images and videos from any compatible MCP client.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables text-to-image and text-to-video generation via the Agnes AI API, with support for multiple models, async video generation, and automatic file downloads.61MIT
- AlicenseAqualityCmaintenanceGenerate images with OpenAI and Google Gemini directly from any MCP client, saving assets into your project with batch support and explicit file output.218 npmMIT
- AlicenseAqualityBmaintenanceImage tools for coding agents: generate from text, edit one reference image, remove backgrounds, upscale 2x, and create reference-based sprite animations. The MCP server, CLI and REST API share one key, credit balance and request history. Needs a DreamLayer API key and paid credits; sprite sheets are beta.747 npmMIT
- AlicenseAqualityBmaintenanceEnables video and image generation from any MCP client, with support for models like Veo 3.1, Grok Imagine, and Nano Banana, including text-to-video, image-to-video, image generation and editing.478 npmMIT