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