mediamcp

---

生成的文件始终会保存到磁盘（默认保存在 ~/Pictures/mediamcp），每条回复都会包含文件的绝对路径和一个小型内嵌预览——Agent 可以立即看到生成结果。

致 AI Agent： 专为您优化的安装说明见 llms-install.md。

您需要一个 OpenRouter API 密钥——可在 https://openrouter.ai/keys 获取。

快速安装

Claude Code

claude mcp add mediamcp -e OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY -- npx -y mediamcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json），然后重启 Claude Desktop：

{
  "mcpServers": {
    "mediamcp": {
      "command": "npx",
      "args": ["-y", "mediamcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
    }
  }
}

Cursor

或者添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mediamcp": {
      "command": "npx",
      "args": ["-y", "mediamcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "mediamcp": {
      "command": "npx",
      "args": ["-y", "mediamcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
    }
  }
}

VS Code（GitHub Copilot）

或者添加到 .vscode/mcp.json（密钥会单独请求，不会写入文件）：

{
  "servers": {
    "mediamcp": {
      "command": "npx",
      "args": ["-y", "mediamcp"],
      "env": { "OPENROUTER_API_KEY": "${input:openrouter-key}" }
    }
  },
  "inputs": [
    {
      "id": "openrouter-key",
      "type": "promptString",
      "password": true,
      "description": "OpenRouter API key (https://openrouter.ai/keys)"
    }
  ]
}

你的 Agent 能做什么

安装后，只需告诉 Agent 类似这样的内容：“为我的落地页生成一张主视觉图，16:9”、“移除 logo.png 的背景”、“制作一段 8 秒的日落海浪视频” 或 “将 logo.png 制作成一段 4 秒的视频”（图生视频）。Agent 会自行选择合适的工具：

工具	功能
generate_image	文本 → 图像（一个或多个）。保存到磁盘，返回路径和内嵌预览。支持 count（最多 4 个变体）、aspect_ratio 和 model 覆盖。
edit_image	现有图像（一个或多个）+ 指令 → 编辑后的图像。接受文件路径、https:// 和 data: URL；多个来源可用于合并图像，制作成一张构图。
generate_video	文本 → 视频 或图片 → 视频（异步任务，通常需要 1–5 分钟）。传入 first_frame_image 可将现有图片制作成动态视频（图生视频）；传入 last_frame_image 可指定最后一帧；传入 reference_images 可作为风格参考。需要使用 i2v 模型（bytedance/seedance-2.0、bytedance/seedance-2.0-fast、google/veo-3.1）。等待任务完成，保存 mp4 并返回路径。超时时返回 polling_url。
check_video_status	根据 polling_url / id 恢复等待视频任务；任务完成后下载结果。
list_models	列出支持图像/视频的模型标识和价格，Agent 可据此自行选择模型。
check_config	诊断：检查密钥是否存在且有效、端点、默认值，以及输出目录是否可写。如果遇到问题，请先运行此工具。

配置

所有设置均通过 MCP 客户端配置中 env 区块里的环境变量完成：

变量	默认值	用途
OPENROUTER_API_KEY	—	必填。 你的 OpenRouter 密钥。
MEDIAMCP_API_KEY	—	供非 OpenRouter 端点使用的 OPENROUTER_API_KEY 别名；如果同时设置了两个变量，则优先使用此变量。
MEDIAMCP_BASE_URL	https://openrouter.ai/api/v1	任何兼容 OpenAI 的 API 的根 URL。
MEDIAMCP_MODEL	google/gemini-2.5-flash-image	默认图像模型标识。
MEDIAMCP_VIDEO_MODEL	google/veo-3.1	默认视频模型标识。
MEDIAMCP_OUTPUT_DIR	~/Pictures/mediamcp	生成文件的保存位置（如果 ~/Pictures 不存在，则使用 ~/mediamcp）。
MEDIAMCP_TIMEOUT_MS	120000	每个请求的 HTTP 超时时间。
MEDIAMCP_PREVIEW	true	随每个结果返回内嵌预览（设为 false 则仅返回路径）。
MEDIAMCP_PREVIEW_MAX_DIM	768	内嵌预览较长一边的像素尺寸。
MEDIAMCP_SCHEMA_DIALECT	2020-12	发布工具 Schema 时使用的 JSON Schema 方言。设为 draft-7 时，按原样返回 MCP SDK 的输出。

使用其他提供商

将 MEDIAMCP_BASE_URL 设为任意兼容 OpenAI 的端点，并设置相应的密钥：

"env": {
  "MEDIAMCP_BASE_URL": "https://your-endpoint.example.com/v1",
  "MEDIAMCP_API_KEY": "your-key",
  "MEDIAMCP_MODEL": "your/image-model"
}

mediamcp 会自动检测端点支持的 API 格式：专用 /images 端点（OpenRouter）、/images/generations（经典 OpenAI）或支持图像的 chat/completions；并记住第一个成功的选项。

问题诊断

1. 请 Agent 运行工具 check_config——它会告知具体的配置错误及修复方法。
2. 也可以在终端中运行相同的诊断：npx -y mediamcp --check（使用 shell 的环境变量）。
3. 常见问题：
   • “No API key configured”——将 OPENROUTER_API_KEY 添加到 MCP 客户端配置中服务器条目的 env 块（而不仅仅是 shell 配置文件），然后重启客户端。
   • “Out of credits (HTTP 402)”——前往 https://openrouter.ai/credits 充值。
   • “Not found (HTTP 404) … for model”——模型的 slug 不正确；运行 list_models。
   • 客户端没有任何反应——确认已安装 Node.js ≥ 20（node --version）。
   • “Tool '…' has an invalid outputSchema … unsupported dialect”——客户端仅根据 JSON Schema 2020-12 验证架构。mediamcp 默认发布 2020-12，因此此错误表示版本过旧：请升级，并确认 check_config 显示 tool schema dialect: 2020-12。

开发

git clone https://github.com/legolev/mediamcp && cd mediamcp
npm install
npm run build       # сборка в dist/index.js
npm test            # юнит-тесты (vitest)
npm run inspect     # открыть MCP Inspector с собранным сервером

许可证

MIT

---

_{mcp-name: io.github.legolev/mediamcp}