内容
<div align="center">
<img src="https://raw.githubusercontent.com/legolev/mediamcp/main/assets/banner.png" alt="mediamcp" width="100%" />
### 教会任何一个 AI 代理创建图像和视频
**mediamcp** — 是一个 MCP 服务器，它连接您的 AI 助手 — Claude Code、Claude Desktop、<br/>
Cursor、Windsurf、VS Code 或任何其他支持 MCP 的客户端与云媒体模型<br/>
（Gemini Flash Image、GPT-5 Image、Seedream、Veo、Sora 等）通过 [OpenRouter](https://openrouter.ai) 或任何 OpenAI 兼容 API。
[](https://www.npmjs.com/package/mediamcp)
[](https://github.com/legolev/mediamcp/actions/workflows/ci.yml)
[](https://nodejs.org)
[](LICENSE)
[English](README.en.md) |
<sub>⭐ 上方的横幅由 mediamcp 自身生成 — 只需调用一次 `generate_image`。</sub>
</div>
---
生成的图像和视频文件始终保存到磁盘（默认为 `~/Pictures/mediamcp`），每个响应都包含文件的绝对路径和一个小预览图像 — 代理可以立即看到结果。
> **对于 AI 代理：** 专门为您优化的安装说明位于 [llms-install.md](llms-install.md)。
**您需要 OpenRouter 的 API 密钥** — 您可以在 <https://openrouter.ai/keys> 获取。
## 快速安装
### Claude Code
```bash
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：
```json
{
"mcpServers": {
"mediamcp": {
"command": "npx",
"args": ["-y", "mediamcp"],
"env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
}
}
}
```
### Cursor
[](https://cursor.com/en/install-mcp?name=mediamcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1lZGlhbWNwIl0sImVudiI6eyJPUEVOUk9VVEVSX0FQSV9LRVkiOiJZT1VSX09QRU5ST1VURVJfS0VZIn19)
或者在 `~/.cursor/mcp.json` 中添加：
```json
{
"mcpServers": {
"mediamcp": {
"command": "npx",
"args": ["-y", "mediamcp"],
"env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
}
}
}
```
### Windsurf
在 `~/.codeium/windsurf/mcp_config.json` 中添加：
```json
{
"mcpServers": {
"mediamcp": {
"command": "npx",
"args": ["-y", "mediamcp"],
"env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
}
}
}
```
### VS Code (GitHub Copilot)
[](https://vscode.dev/redirect/mcp/install?name=mediamcp&config=%7B%22name%22%3A%22mediamcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mediamcp%22%5D%2C%22env%22%3A%7B%22OPENROUTER_API_KEY%22%3A%22YOUR_OPENROUTER_KEY%22%7D%7D)
或者在 `.vscode/mcp.json` 中添加（需要单独请求密钥，不会出现在文件中）：
```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)"
}
]
}
```
## 您的代理可以执行的操作
安装完成后，只需告诉代理执行类似 *「为我的着陆页生成 hero 图像，16:9」*、*「从 logo.png 删除背景」* 或 *「创建一个 8 秒的海浪日落视频」* 的操作。代理将自动选择合适的工具：
| 工具 | 功能 |
| --- | --- |
| `generate_image` | 文本 → 图像（一个或多个）。保存到磁盘，返回路径和内嵌预览。支持 `count`（最多 4 个变体）、`aspect_ratio` 和模型覆盖。 |
| `edit_image` | 现有图像（一个或多个）+ 指令 → 编辑后的图像。接受文件路径、`https://` 和 `data:` URL；多个源用于将图像组合成一个合成图像。 |
| `generate_video` | 文本 → 视频（异步任务，通常 1-5 分钟）。等待结果，保存 mp4，返回路径。超时时返回 `polling_url`，可以重新开始等待。 |
| `check_video_status` | 通过 `polling_url` / id 恢复视频任务等待；在准备好时下载结果。 |
| `list_models` | 列出支持图像/视频的模型的 slug 和价格 — 代理可以选择模型。 |
| `check_config` | 诊断：API 密钥、端点、默认值和输出目录的配置和有效性。如果有问题 — 先运行它。 |
## 配置
所有配置都可以通过 MCP 客户端配置块中的 `env` 部分的变量进行：
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `OPENROUTER_API_KEY` | — | **必填**。您的 OpenRouter 密钥。 |
| `MEDIAMCP_API_KEY` | — | OpenRouter 的别名；如果同时设置了两个变量，则优先。 |
| `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_BASE_URL` 中指定任何 OpenAI 兼容的端点，并提供相应的密钥：
```json
"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. 请求代理运行 **`check_config`** 工具 — 它将报告配置错误以及如何修复。
2. 也可以在终端中运行诊断：`npx -y mediamcp --check`（使用 shell 环境变量）。
3. 常见问题：
- **「No API key configured」** — 在 MCP 客户端配置块的 `env` 部分添加 `OPENROUTER_API_KEY`（而不仅仅是 shell 配置文件），然后重启客户端。
- **「Out of credits (HTTP 402)」** — 在 <https://openrouter.ai/credits> 充值。
- **「Not found (HTTP 404) … for model」** — 无效的模型 slug；运行 `list_models`。
- **客户端无反应** — 确保已安装 Node.js ≥ 20（`node --version`）。
## 开发
```bash
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](LICENSE)
---
<sub>mcp-name: io.github.legolev/mediamcp</sub>
