Content
<div align="center">
<img src="https://raw.githubusercontent.com/legolev/mediamcp/main/assets/banner.png" alt="mediamcp" width="100%" />
### Teach any AI agent to create images and videos
**mediamcp** — a MCP server that connects your AI assistant — Claude Code, Claude Desktop,<br/>
Cursor, Windsurf, VS Code or any other MCP-enabled client — to cloud media models<br/>
(Gemini Flash Image, GPT-5 Image, Seedream, Veo, Sora, …) via [OpenRouter](https://openrouter.ai) or any OpenAI-compatible 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>⭐ The banner above was generated by mediamcp itself — one call to `generate_image`.</sub>
</div>
---
Generated files are always saved to disk (by default to `~/Pictures/mediamcp`), and each response contains the absolute file path and a small embedded preview — the agent immediately sees what it got.
> **For AI agents:** installation instructions optimized for you are in [llms-install.md](llms-install.md).
**You will need an OpenRouter API key** — you can get it at <https://openrouter.ai/keys>.
## Quick Installation
### Claude Code
```bash
claude mcp add mediamcp -e OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY -- npx -y mediamcp
```
### Claude Desktop
Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and restart 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)
Or add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"mediamcp": {
"command": "npx",
"args": ["-y", "mediamcp"],
"env": { "OPENROUTER_API_KEY": "sk-or-v1-YOUR_KEY" }
}
}
}
```
### Windsurf
Add to `~/.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)
Or add to `.vscode/mcp.json` (the key is requested separately and does not fall into the file):
```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)"
}
]
}
```
## What your agent can do
After installation, simply tell the agent something like *“generate a hero image for my landing, 16:9”*, *“remove the background from logo.png”*, or *“make an 8-second video with ocean waves at sunset”*. The agent will choose the right tool:
| Tool | What it does |
| --- | --- |
| `generate_image` | Text → image (one or more). Saves to disk, returns path and embedded preview. Supports `count` (up to 4 variations), `aspect_ratio`, and overriding `model`. |
| `edit_image` | Existing image (one or more) + instruction → edited image. Accepts file paths, `https://`- and `data:`-URLs; multiple sources — for combining images into one composition. |
| `generate_video` | Text → video (asynchronous task, usually 1–5 minutes). Waits for the result, saves mp4, returns path. On timeout, returns `polling_url`, by which you can resume waiting. |
| `check_video_status` | Resumes waiting for a video task by `polling_url` / id; upon readiness, downloads the result. |
| `list_models` | Outputs slugs and prices of models with image/video support — the agent can choose the model itself. |
| `check_config` | Diagnostics: presence and validity of the key, endpoint, default values, and the ability to write to the output directory. If something doesn’t work, run it first. |
## Configuration
Everything is configured through environment variables in the `env` block of your MCP client configuration:
| Variable | Default | Purpose |
| --- | --- | --- |
| `OPENROUTER_API_KEY` | — | **Required.** Your OpenRouter key. |
| `MEDIAMCP_API_KEY` | — | Alias for `OPENROUTER_API_KEY` for non-OpenRouter endpoints; takes precedence if both variables are set. |
| `MEDIAMCP_BASE_URL` | `https://openrouter.ai/api/v1` | Root URL of any OpenAI-compatible API. |
| `MEDIAMCP_MODEL` | `google/gemini-2.5-flash-image` | Default image model slug. |
| `MEDIAMCP_VIDEO_MODEL` | `google/veo-3.1` | Default video model slug. |
| `MEDIAMCP_OUTPUT_DIR` | `~/Pictures/mediamcp` | Where to save generated files (`~/mediamcp` if `~/Pictures` does not exist). |
| `MEDIAMCP_TIMEOUT_MS` | `120000` | HTTP timeout per request. |
| `MEDIAMCP_PREVIEW` | `true` | Return an embedded preview with each result (`false` — only paths). |
| `MEDIAMCP_PREVIEW_MAX_DIM` | `768` | Long side of the embedded preview in pixels. |
### Using a different provider
Specify any OpenAI-compatible endpoint in `MEDIAMCP_BASE_URL` and set the corresponding key:
```json
"env": {
"MEDIAMCP_BASE_URL": "https://your-endpoint.example.com/v1",
"MEDIAMCP_API_KEY": "your-key",
"MEDIAMCP_MODEL": "your/image-model"
}
```
mediamcp itself determines which API format the endpoint supports: a dedicated `/images` endpoint (OpenRouter), `/images/generations` (classic OpenAI), or `chat/completions` with image support — the first working option is remembered.
## Troubleshooting
1. Ask the agent to run the **`check_config`** tool — it will report what is configured incorrectly and how to fix it.
2. The same diagnostics can be run from the terminal: `npx -y mediamcp --check` (uses your shell’s environment variables).
3. Typical issues:
- **“No API key configured”** — add `OPENROUTER_API_KEY` to the `env` block of the server entry in the MCP client configuration (not just to the shell profile) and restart the client.
- **“Out of credits (HTTP 402)”** — top up your balance at <https://openrouter.ai/credits>.
- **“Not found (HTTP 404) … for model”** — incorrect model slug; run `list_models`.
- **Nothing happens in the client** — make sure Node.js ≥ 20 is installed (`node --version`).
## Development
```bash
git clone https://github.com/legolev/mediamcp && cd mediamcp
npm install
npm run build # build to dist/index.js
npm test # unit tests (vitest)
npm run inspect # open MCP Inspector with the built server
```
## License
[MIT](LICENSE)
---
<sub>mcp-name: io.github.legolev/mediamcp</sub>
