imagine-mcp

Compreensão e geração de imagens e vídeos

Documentação

imagine-mcp

mcp-name: io.github.n24q02m/imagine-mcp

Compreensão e geração de imagens e vídeos para agentes de IA — em Gemini, OpenAI e Grok.

Projetos irmãos de n24q02m (clique para expandir)

Projeto	Tagline	Tag
agent-chat-plugin	Agentes de IA pares conversam em uma pasta compartilhada — sem retransmissão humana, sem orquestrador, tra...	Ferramentas
better-code-review-graph	Grafo de conhecimento para revisões de código eficientes em tokens — busca semântica e cham...	MCP
better-drive	Sincronização bidirecional do Google Drive com filtro .driveignore — mecanismo rclone, bandeja do Windows	Ferramentas
better-email-mcp	E-mail IMAP/SMTP para agentes de IA — ler, enviar, organizar pastas e gerenciar anex...	MCP
better-godot-mcp	Servidor MCP composto para Godot Engine — 17 ferramentas compostas para desenvolvimento assistido por IA...	MCP
better-notion-mcp	Notion com foco em Markdown para agentes de IA — páginas, bancos de dados, blocos e comentários...	MCP
better-semantic-release	Fork drop-in do python-semantic-release com proteções de segurança de release embutidas (orp...	Ferramentas
better-telegram-mcp	Telegram para agentes de IA — mensagens, chats, mídia e contatos em ambos os bo...	MCP
better-workspace-mcp	Servidor MCP do Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Marketplace de plugins do Claude Code para os servidores MCP da n24q02m — instale busca web...	Marketplace
imagine-mcp	Compreensão e geração de imagens e vídeos para agentes de IA — em Gemini, Op...	MCP
jules-task-archiver	Extensão do Chrome para operações em lote em tarefas do Jules via API batchexecute — a...	Ferramentas
mcp-core	Fundação compartilhada para construir servidores MCP — transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memória de IA persistente com busca híbrida e sincronização embutida. Aberto, gratuito, ilimit...	MCP
qwen3-embed	Embedding e reranking de texto Qwen3 leve via ONNX Runtime e GGUF	Biblioteca
skret	Segredos sem o servidor.	CLI
tacet	Uma cascata neuro-simbólica autodestilante que amortiza o custo de LLM em conhecimento...	Ferramentas
web-core	Pacote de infraestrutura web compartilhada para busca, scraping, segurança HTTP e st...	Biblioteca
wet-mcp	Servidor MCP de código aberto para agentes de IA: busca web, extração de conteúdo e lib...	MCP

Recursos

Compreensão multimodal — Descreva, classifique ou raciocine sobre imagens e vídeos (o Gemini lida com imagem + vídeo mistos em uma única chamada)
Geração de imagens — Texto para imagem e imagem para imagem (edição / inpaint) em Gemini Imagen, OpenAI gpt-image, Grok Imagine
Geração de vídeos — Texto para vídeo e imagem para vídeo (Gemini Veo 3.1, Grok Imagine Video)
3 provedores x 2 níveis — Mesma interface para gemini / openai / grok em poor (barato/rápido) ou rich (alta qualidade); alterne via parâmetro
Passagem de modelo aberto — A compreensão é roteada pelo litellm; passe qualquer provider/model ou configure uma cadeia de modelos ordenada (sem catálogo fixo)
Modo degradado — O servidor inicia sem credenciais e expõe os provedores restantes conforme você adiciona chaves
Cache de respostas — Cache em disco de respostas understand com TTL configurável
Transporte duplo — stdio puro com variáveis de ambiente do provedor (padrão) ou HTTP multiusuário com formulário de relay de token de colagem

Instalação

Execute com uvx (sem etapa de instalação) ou baixe a imagem do contêiner:

# uvx -- recommended, runs the published PyPI package
uvx imagine-mcp

# Docker
docker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest

Adicione-o a um cliente MCP apontando o cliente para o comando uvx imagine-mcp e fornecendo pelo menos uma chave de provedor (veja Configuração):

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": { "GEMINI_API_KEY": "AIza..." }
    }
  }
}

Para trechos por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) e a configuração HTTP baseada em navegador, veja a documentação de configuração.

Instale com um agente de IA — cole isto no seu agente de codificação de IA:

Instale o servidor MCP imagine-mcp seguindo os passos em https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md

Smithery

O imagine-mcp inclui um smithery.yaml para que possa ser instalado e executado via Smithery. A entrada inicia o pacote PyPI publicado via stdio (uvx --python 3.13 imagine-mcp) com um esquema de configuração vazio — nenhum campo de configuração é necessário no momento da implantação. As chaves do provedor são fornecidas em tempo de execução pelo próprio fluxo de credenciais do servidor (variáveis de ambiente no modo stdio, ou o formulário de configuração no navegador no modo HTTP; veja Configuração).

Configuração

Dois transportes (padrão stdio; opte por http com --http, MCP_TRANSPORT=http ou TRANSPORT_MODE=http):

stdio (padrão) — usuário único, lê credenciais apenas de variáveis de ambiente. Sai se nenhuma das três chaves do provedor estiver definida.
http — daemon HTTP. Self-host local em 127.0.0.1 por padrão, ou remoto multiusuário (isolamento de credenciais por JWT-sub) quando PUBLIC_URL + MCP_DCR_SERVER_SECRET estão definidos. No modo HTTP, as credenciais são inseridas por meio de um formulário no navegador em /authorize.

Chaves do provedor

Todas opcionais — o servidor inicia em modo degradado e expõe os provedores que tiverem uma chave. Defina pelo menos uma.

Variável de ambiente	Provedor	Obtenha uma chave em
`GEMINI_API_KEY`	Gemini (imagem + vídeo)	aistudio.google.com/apikey
`OPENAI_API_KEY`	OpenAI (imagem)	platform.openai.com/api-keys
`XAI_API_KEY`	Grok / xAI (imagem + vídeo)	console.x.ai

Quando uma ferramenta é chamada sem um provider explícito, a primeira chave presente vence na ordem XAI_API_KEY -> OPENAI_API_KEY -> GEMINI_API_KEY.

Cadeias de modelos (opcional)

A escolha do modelo passa diretamente para o litellm (understand) ou para o SDK nativo do provedor (generate) — não há catálogo de modelos fixo. Cada cadeia é um CSV de entradas provider/model do litellm; a ordem é a ordem de fallback.

Variável de ambiente	Propósito
`UNDERSTAND_MODELS`	Cadeia de modelos ordenada para `understand` (fallback do litellm). Vazia e sem `model` explícito -> `understand` falha ruidosamente (sem padrão embutido).
`GENERATE_MODELS`	Cadeia de modelos ordenada para `generate`. A primeira entrada seleciona o provedor nativo + modelo. Vazia -> o padrão mínimo embutido do próprio provedor.
`GENERATE_PROVIDER_PRIORITY`	CSV de nomes de provedores reordenando o fallback automático de geração. Padrão: `grok,openai,gemini`.

A compreensão é roteada pelo litellm (passagem provider/model), então qualquer provedor do litellm funciona — forneça o <PROVIDER>_API_KEY desse provedor. A geração permanece nos SDKs nativos dos provedores (Gemini, OpenAI, Grok). Exemplo:

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/<model-id>,openai/<model-id>",
        "GEMINI_API_KEY": "AIza...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Ajustes de tempo de execução

config(action="set", key=..., value=...) ajusta log_level, default_provider, default_tier e cache_ttl_seconds em tempo de execução.

CLI

O comando de console imagine-mcp instalado pelo pacote não aceita subcomandos — ele inicia o servidor MCP diretamente. O transporte é selecionado por uma única flag ou seus equivalentes de variável de ambiente:

imagine-mcp            # stdio transport (default); reads provider keys from env vars
imagine-mcp --http     # HTTP daemon; credentials via the browser setup form

Invocação	Ambiente equivalente	Resultado
`imagine-mcp`	`MCP_TRANSPORT` não definido	stdio, usuário único, credenciais por variável de ambiente
`imagine-mcp --http`	`MCP_TRANSPORT=http` (ou `TRANSPORT_MODE=http`)	daemon HTTP — self-host local `127.0.0.1`, ou remoto multiusuário quando `PUBLIC_URL` + `MCP_DCR_SERVER_SECRET` estão definidos

No modo stdio, o servidor sai se nenhuma das chaves do provedor estiver definida. Os ajustes de bind HTTP remoto (MCP_HOST, MCP_PORT) se aplicam apenas quando PUBLIC_URL está definido; veja Configuração.

Remoto (modo HTTP)

Uma implantação HTTP atende clientes que suportam servidores MCP HTTP remotos. Ela é protegida por OAuth — uma solicitação não autenticada retorna 401 com um desafio WWW-Authenticate: Bearer — e as credenciais são provisionadas pelo formulário de configuração no navegador. Aponte um cliente MCP compatível com HTTP para https://<your-host>/mcp e conclua o fluxo OAuth para conectar. Para criar uma, veja Implantar no Cloudflare.

Documentação

Documentação completa em mcp.n24q02m.com/servers/imagine-mcp/setup/:

Configuração — métodos de instalação para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Visão geral dos modos — stdio / relay local / relay remoto / OAuth remoto
Configuração multiusuário — modelo de credenciais por JWT-sub

Ferramentas

Ferramenta	Ações	Descrição
`understand`	--	Descreva ou raciocine sobre uma ou mais URLs de imagem/vídeo. `media_urls: list[str]`, `prompt: str`, `provider`, `tier`, `max_tokens`.
`generate`	--	Gere uma imagem ou vídeo a partir de um prompt de texto. `media_type: image\|video`, opcional `reference_image_url`, opcional `job_id` (poll de vídeo), `aspect_ratio`, `duration_seconds`.
`config`	`setup_status`, `setup_skip`, `setup_reset`, `setup_complete`, `warmup`, `status`, `set`, `cache_clear` (`relay_status`/`relay_skip`/`relay_reset`/`relay_complete` honrados como aliases obsoletos)	Credencial + configuração de tempo de execução: verifique o estado da credencial, defina ajustes de tempo de execução (nível de log, provedor padrão, TTL), limpe o cache de respostas.
`help`	--	Documentação completa em Markdown para tópicos `understand`, `generate` ou `config`.
`config__open_relay`	--	Auxiliar injetado pelo framework (mcp-core); abre o formulário de credenciais no navegador.

A escolha do modelo é orientada pelo chamador (passagem provider/model do litellm ou uma cadeia de env *_MODELS) — veja Cadeias de modelos acima.

Comparação

Como o imagine-mcp se compara aos concorrentes diretos em cada pilar:

Capacidade	imagine-mcp	EverArt MCP	fal.ai MCP	Replicate Flux MCP
Compreensão de imagem/vídeo	Sim (descrever / classificar / raciocinar sobre URLs de imagem + vídeo)	Não	Não	Não
Geração de imagem	Sim (texto-para-imagem + imagem-para-imagem via `reference_image_url`)	Sim (único `generate_image`)	Sim (texto/imagem-para-imagem, edição, inpaint)	Sim (único `generate_image`)
Geração de vídeo	Sim (texto-para-vídeo + imagem-para-vídeo, poll assíncrono `job_id`)	Não	Sim (texto/imagem-para-vídeo)	Não
Backends multi-provedores	Sim (Gemini / OpenAI / Grok, fallback automático)	Não (somente EverArt)	Não (somente fal.ai)	Não (somente Replicate Flux)
Níveis de qualidade/custo	Sim (`poor` barato-rápido vs `rich` alta qualidade por provedor)	Não	Não	Não
Auto-hospedável / código aberto	Sim (Apache-2.0, stdio + HTTP auto-hospedado)	Sim (MIT, arquivado)	Sim (MIT)	Sim (MIT, arquivado)

Segurança

Prevenção de SSRF + LFI -- Todos os media_urls e reference_image_url são validados no limite de despacho; apenas os esquemas http:// e https:// chegam aos provedores. file://, ftp://, gopher:// e URLs sem esquema são rejeitados.
Sem credenciais em erros -- Erros do lado do provedor são sanitizados antes de serem retornados.
Inicialização degradada -- Credenciais ausentes não impedem o servidor de iniciar; ações afetadas exibem erros acionáveis em vez de travar na inicialização.
Armazenamento de credenciais -- Credenciais enviadas pelo formulário de credenciais do navegador são armazenadas criptografadas via mcp-core (AES-GCM, chave vinculada à máquina) em ~/.imagine-mcp/config.json.

Nome de usuário do workspace (formulário de configuração HTTP)

O formulário de credenciais do navegador tem um campo opcional nome de usuário do workspace. Inserir o mesmo nome de usuário sempre leva você ao mesmo bucket por sub, então suas chaves de provedor permanecem acessíveis após uma reautorização e entre dispositivos, em vez de ficarem vinculadas ao sujeito único gerado para cada ida e volta de /authorize. Deixar em branco mantém o comportamento anterior de autorização por usuário.

Limite de confiança: quando o formulário é protegido por um compartilhado MCP_RELAY_PASSWORD, o nome de usuário é uma chave de partição, não um segredo -- qualquer pessoa que conheça essa senha pode digitar qualquer nome de usuário e alcançar esse bucket. Isso é aceitável para um grupo confiável; uma implantação multi-tenant não confiável precisa de um segredo por usuário ou OAuth delegado em vez disso.

Migração única: usuários existentes devem reinserir suas credenciais uma vez após essa mudança. Nada é excluído; credenciais armazenadas sob o antigo sujeito aleatório simplesmente não são mais endereçadas.

Compilar a partir do código-fonte

git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup      # or: uv sync --group dev
mise run dev        # run the server in stdio mode (add --http for the HTTP daemon)

Implantar no Cloudflare

Execute sua própria instância do imagine serverless no Cloudflare (Worker + Container + KV). O armazenamento é somente KV -- o cofre de credenciais por usuário fica no KV, e a geração retorna apenas base64 porque o sistema de arquivos do container é efêmero (IMAGINE_OUTPUT_MODE=base64).

Pré-requisitos: uma conta Cloudflare no plano Workers Paid -- necessário para Containers (o nível gratuito do Cloudflare não inclui Containers) -- e a CLI wrangler.

git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp
wrangler login
Crie o namespace KV (imagine é somente KV -- sem D1 ou Vectorize) e cole o id retornado em wrangler.jsonc (o placeholder <imagine-kv-namespace-id>):
```
wrangler kv namespace create imagine-kv
```

Envie a imagem do container para o seu registro gerenciado do Cloudflare (os Containers da CF não podem puxar de registros externos diretamente) e defina <YOUR_ACCOUNT_ID> em wrangler.jsonc:

docker pull ghcr.io/n24q02m/imagine-mcp:beta
docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta
wrangler containers push imagine-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/imagine-mcp:beta

Aponte os placeholders wrangler.jsonc restantes para o seu próprio domínio: <YOUR_PUBLIC_URL> (o vars.PUBLIC_URL, ex.: https://imagine.example.com) e <YOUR_WORKER_DOMAIN> (o padrão de domínio personalizado routes, ex.: imagine.example.com).
Defina os segredos. CREDENTIAL_SECRET (chave estável de assinatura JWT + chave do cofre por usuário) e MCP_DCR_SERVER_SECRET (prova de uma implantação multi-usuário intencional) são obrigatórios; MCP_RELAY_PASSWORD controla o login do formulário de configuração do navegador. As chaves do provedor são opcionais padrões do servidor -- os usuários normalmente colam as suas próprias através do formulário de configuração:
```
wrangler secret put CREDENTIAL_SECRET
wrangler secret put MCP_DCR_SERVER_SECRET
wrangler secret put MCP_RELAY_PASSWORD
wrangler secret put GEMINI_API_KEY       # optional provider default
wrangler secret put OPENAI_API_KEY       # optional provider default
wrangler secret put XAI_API_KEY          # optional provider default
```
wrangler deploy, então abra o domínio do seu Worker e finalize a configuração no formulário de relay do navegador.

A imagem do container http já executa multi-usuário (MCP_TRANSPORT=http está embutido no alvo da imagem). O armazenamento mapeia para o Cloudflare via MCP_STORAGE_BACKEND=cf-kv (cofre de credenciais criptografado) com IMAGINE_OUTPUT_MODE=base64, que força respostas base64 para que nenhum caminho de mídia seja gravado no sistema de arquivos efêmero do container.

Modelo de Confiança

Este plugin implementa TC-Local (vinculado à máquina, princípio de confiança único). Veja modelo de confiança do mcp-core para a classificação completa.

Modo	Armazenamento	Criptografia	Quem pode ler seus dados?
stdio (padrão)	`~/.imagine-mcp/config.json`	AES-GCM, chave vinculada à máquina	Somente o usuário do seu SO (permissão de arquivo 0600)
HTTP auto-hospedado	Igual ao stdio	Igual	Somente você (admin = usuário)

Contribuindo

Veja CONTRIBUTING.md para o fluxo de trabalho completo de desenvolvimento, convenção de commits e processo de lançamento. Issues + Discussões são bem-vindas.

Licença

Apache-2.0 -- veja LICENSE.