agnes-mcp
基于 Agnes AI 的 MCP 服务端 — 读图·生图·生视频，全部走 OpenAI 兼容接口。
官方仓库：AgnesAI-Labs/AgnesAI-Models — 模型目录、API 文档和示例。API 平台：https://platform.agnes-ai.com/
工具列表
| 工具 | 说明 |
|---|---|
describe_image |
读本地图片 → 自动压缩 → base64 → Agnes 视觉模型 → 返回文字描述。支持 png/jpg/webp/bmp/gif |
generate_image |
文字生图（异步）→ 返回 taskId: "img_1"，后台自动下载 |
generate_video |
文字生视频（异步）→ 返回 taskId: "vid_1"，后台自动轮询并下载 |
get_task_status |
查询任意异步任务状态（0ms 缓存，不调 API）→ 完成后返回下载路径 + 总耗时 |
describe_image
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
filePath |
string | 是 | — | 本地图片路径，支持 png/jpg/jpeg/gif/webp/bmp |
prompt |
string | 否 | "Describe this image in detail" |
传给视觉模型的提示词 |
返回：文字描述 + 耗时
generate_image
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
prompt |
string | 是 | — | 生成图片的文字描述 |
size |
string | 否 | "1024x768" |
期望尺寸，如 "1024x768"、"512x512"（实际由 Agnes 决定最终分辨率） |
outputPath |
string | 是 | — | 图片保存路径 |
返回：{"taskId":"img_1","status":"queued"}
generate_video
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
prompt |
string | 是 | — | 生成视频的文字描述 |
outputPath |
string | 是 | — | 视频保存路径 |
返回：{"taskId":"vid_1","status":"queued"}
get_task_status
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
taskId |
string | 是 | — | 异步任务 ID，img_* 或 vid_* |
返回：{"status":"completed","outputPath":"...","totalTime":"26s"} 或 {"status":"in_progress","progress":30}
快速开始
npm install
# 编辑 config.json 填入 Agnes API key
npm run dev
配置
编辑项目根目录的 config.json：
{
"apiKeys": ["sk-xxx", "sk-yyy"],
"baseUrl": "https://apihub.agnes-ai.com/v1",
"models": {
"vision": "agnes-2.0-flash",
"image": "agnes-image-2.1-flash",
"video": "agnes-video-v2.0"
},
"videoTimeout": 600000,
"imageMaxDimension": 2048,
"imageQuality": 80
}
| 字段 | 默认值 | 说明 |
|---|---|---|
apiKeys |
[] |
多个 key 自动轮询（round-robin） |
baseUrl |
https://apihub.agnes-ai.com/v1 |
API 地址 |
models.* |
agnes-2.0-flash 等 | 各任务使用模型 |
videoTimeout |
600000 |
视频生成超时（毫秒），默认 10 分钟 |
imageMaxDimension |
2048 |
读图时最大宽/高，超过等比缩小 |
imageQuality |
80 |
JPEG 压缩质量（保留以备后续扩展） |
retryCount |
3 |
API 请求失败时自动重试次数（对 429/5xx/网络错误生效） |
config.json 已被 .gitignore 和 pre-commit 钩子双重保护，禁止提交到仓库。
环境变量
| 变量 | 作用 |
|---|---|
AGNES_BASE_URL |
覆盖 API 地址（默认使用 config.json） |
AGNES_API_KEYS |
JSON 数组格式的 key 列表（优先级高于 config.json） |
接入 MCP Host
opencode.json
{
"mcp": {
"agnes-mcp": {
"type": "local",
"command": ["npx", "tsx", "src/main.ts"],
"cwd": "D:\\path\\to\\agnes_mcp"
}
}
}
claude_desktop_config.json
{
"mcpServers": {
"agnes-mcp": {
"command": "node",
"args": ["D:\\path\\to\\agnes_mcp\\dist\\main.js"]
}
}
}
确保先执行 npm run build 编译，然后填入实际项目路径。
脚本
| 命令 | 作用 |
|---|---|
npm run dev |
tsx watch src/main.ts 开发模式 |
npm run build |
tsc 编译 |
npm run start |
node dist/main.js 启动 |
许可
MIT © 2026 1cyberlangke1
