mediamcp

---

Os arquivos gerados são sempre salvos em disco (por padrão em ~/Pictures/mediamcp), e cada resposta contém o caminho absoluto do arquivo e uma pequena pré-visualização incorporada — o agente vê imediatamente o que foi produzido.

Para agentes de IA: instruções de instalação otimizadas especialmente para você estão em llms-install.md.

Você precisará de uma chave de API do OpenRouter — obtenha-a em https://openrouter.ai/keys.

Instalação rápida

Claude Code

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

Claude Desktop

Adicione em claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) e reinicie o Claude Desktop:

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

Cursor

Ou adicione em ~/.cursor/mcp.json:

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

Windsurf

Adicione em ~/.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)

Ou adicione em .vscode/mcp.json (a chave é solicitada separadamente e não entra no arquivo):

{
  "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)"
    }
  ]
}

O que seu agente poderá fazer

Após a instalação, basta dizer ao agente algo como "gere uma imagem hero para minha landing page, 16:9", "remova o fundo de logo.png", "faça um vídeo de 8 segundos com ondas do oceano ao pôr do sol" ou "anime logo.png em um vídeo de 4 segundos" (image-to-video). O agente escolherá a ferramenta adequada:

Ferramenta	O que faz
generate_image	Texto → imagem (uma ou várias). Salva em disco, retorna o caminho e uma pré-visualização incorporada. Suporta count (até 4 variações), aspect_ratio e substituição de model.
edit_image	Imagem existente (uma ou várias) + instrução → imagem editada. Aceita caminhos de arquivo, URLs https:// e data:; várias fontes — para combinar imagens em uma única composição.
generate_video	Texto → vídeo ou imagem → vídeo (tarefa assíncrona, geralmente 1–5 minutos). Passe first_frame_image para animar uma imagem existente (image-to-video), last_frame_image — para o quadro final, ou reference_images — como referência de estilo. Requer um modelo i2v (bytedance/seedance-2.0, bytedance/seedance-2.0-fast, google/veo-3.1). Aguarda o resultado, salva o mp4, retorna o caminho. Em caso de timeout, retorna polling_url.
check_video_status	Retoma a espera de uma tarefa de vídeo por polling_url / id; quando pronta, baixa o resultado.
list_models	Exibe slugs e preços de modelos com suporte a imagens/vídeos — o agente poderá escolher o modelo por conta própria.
check_config	Diagnóstico: presença e validade da chave, endpoint, valores padrão, capacidade de gravação no diretório de saída. Se algo não funcionar — execute-o primeiro.

Configuração

Tudo é configurado por variáveis de ambiente no bloco env da configuração do seu cliente MCP:

Variável	Padrão	Finalidade
OPENROUTER_API_KEY	—	Obrigatória. Sua chave do OpenRouter.
MEDIAMCP_API_KEY	—	Alias de OPENROUTER_API_KEY para endpoints diferentes do OpenRouter; tem prioridade se ambas as variáveis forem definidas.
MEDIAMCP_BASE_URL	https://openrouter.ai/api/v1	URL raiz de qualquer API compatível com OpenAI.
MEDIAMCP_MODEL	google/gemini-2.5-flash-image	Slug do modelo de imagem padrão.
MEDIAMCP_VIDEO_MODEL	google/veo-3.1	Slug do modelo de vídeo padrão.
MEDIAMCP_OUTPUT_DIR	~/Pictures/mediamcp	Onde salvar os arquivos gerados (~/mediamcp, se ~/Pictures não existir).
MEDIAMCP_TIMEOUT_MS	120000	Timeout HTTP por requisição.
MEDIAMCP_PREVIEW	true	Retornar pré-visualização incorporada junto com cada resultado (false — apenas caminhos).
MEDIAMCP_PREVIEW_MAX_DIM	768	Lado maior da pré-visualização incorporada em pixels.

Usando outro provedor

Defina em MEDIAMCP_BASE_URL qualquer endpoint compatível com OpenAI e forneça a chave correspondente:

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

O mediamcp detecta automaticamente qual formato de API o endpoint suporta: endpoint dedicado /images (OpenRouter), /images/generations (OpenAI clássico) ou chat/completions com suporte a imagens — a primeira variante que funcionar é memorizada.

Diagnóstico de problemas

1. Peça ao agente para executar a ferramenta check_config — ela informará o que está configurado incorretamente e como corrigir.
2. O mesmo diagnóstico pode ser executado no terminal: npx -y mediamcp --check (usa as variáveis de ambiente do seu shell).
3. Problemas típicos:
   • "No API key configured" — adicione OPENROUTER_API_KEY no bloco env da entrada do servidor na configuração do cliente MCP (não apenas no perfil do shell) e reinicie o cliente.
   • "Out of credits (HTTP 402)" — recarregue seu saldo em https://openrouter.ai/credits.
   • "Not found (HTTP 404) … for model" — slug de modelo incorreto; execute list_models.
   • Nada acontece no cliente — verifique se o Node.js ≥ 20 está instalado (node --version).

Desenvolvimento

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 с собранным сервером

Licença

MIT

---

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