imgx-mcp

Servidor MCP de geração e edição de imagens com IA. Geração de texto para imagem, edição baseada em texto com refinamento iterativo. Múltiplos provedores (Gemini + OpenAI).

GitHubExperimente este MCPPatrocinado

Documentação

imgx-mcp

Servidor MCP de geração e edição de imagens com IA. Funciona com Claude Code, Gemini CLI, Cursor, Windsurf e qualquer ferramenta compatível com MCP.

Gere imagens a partir de texto, edite imagens existentes com instruções de texto, itere sobre os resultados — tudo a partir do seu ambiente de codificação com IA.

O que diferencia o imgx-mcp

Sem engenharia de prompt — Seu agente de IA mantém o contexto da conversa e constrói prompts otimizados automaticamente. Diga o que você precisa; o agente cuida da estrutura do prompt, seleção de modelo e dimensionamento específico da plataforma
24 técnicas de edição integradas — Atmosfera, composição, transferência de estilo, manipulação de elementos e estilos em tendência — agrupadas como uma Skill que seu agente aplica sob demanda
Gerenciamento de sessão com desfazer/refazer — Edite iterativamente, volte a qualquer ponto, crie ramificações ou alterne entre sessões paralelas — controle de versão para imagens

Início rápido

Adicione à configuração MCP da sua ferramenta (.mcp.json, settings.json, etc.):

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

Pronto. Seu agente de IA agora pode gerar e editar imagens.

Windows: Substitua "command": "npx" por "command": "cmd" e adicione "/c" antes do array de argumentos.

Skill (Claude Code)

Para usuários do Claude Code, o imgx-mcp inclui uma skill image-generation — um prompt guiado que ensina o Claude a usar as ferramentas MCP de forma eficaz. Com a skill instalada, digite /image-generation para iniciar um fluxo de trabalho guiado.

Instalar a skill

Copie o diretório da skill do pacote npm ou do repositório GitHub para o seu projeto:

# From npm (after npx has cached the package)
cp -r $(npm root -g)/imgx-mcp/skills .claude/skills

# Or from the GitHub repository
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
  -o .claude/skills/image-generation/SKILL.md --create-dirs
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
  -o .claude/skills/image-generation/references/providers.md --create-dirs

Ou coloque os arquivos da skill manualmente:

your-project/
  .mcp.json                              ← MCP server config (Quick start above)
  .claude/
    skills/
      image-generation/
        SKILL.md                         ← skill prompt
        references/
          providers.md                   ← provider reference

Os arquivos da skill estão incluídos no pacote npm em skills/ e no repositório GitHub.

Skill pessoal (todos os projetos): Coloque em ~/.claude/skills/image-generation/ em vez de .claude/skills/.

Claude Desktop

O Claude Desktop suporta skills via upload de ZIP:

Baixe image-generation-skill.zip do repositório (ou encontre-o no pacote npm em dist/)
No Claude Desktop: Configurações > Perfil > Personalizar > Skills > Adicionar Skill
Envie o ZIP

Atualize a skill baixando e enviando novamente o ZIP após novos lançamentos.

O que a Skill oferece

O servidor MCP dá à IA a capacidade de gerar e editar imagens. A Skill adiciona o conhecimento de como usar essas ferramentas bem — para que você não precise aprender sintaxe de prompt, especificações de modelo ou parâmetros específicos de serviço.

Construção automática de prompts — Diga "Preciso de uma imagem de capa." A IA constrói um prompt estruturado usando o framework Sujeito-Contexto-Estilo: o que mostrar, onde colocar, como deve parecer
24 técnicas de edição — Ajuste de atmosfera, mudanças de composição, manipulação de elementos, transferência de estilo. "Deixe mais quente" ou "adicione profundidade de campo" — a IA seleciona a instrução correta para o modelo
Seleção inteligente de modelo — Começa com o modelo gratuito. Sugere upgrades pagos apenas quando suas necessidades excedem os recursos do nível gratuito e explica o que muda
Dimensionamento consciente da plataforma — "OGP do Twitter" ou "captura de tela da App Store" — a IA escolhe a proporção e resolução corretas. Cobre redes sociais, OGP, lojas de aplicativos, impressão e plataformas de blog
Modelos de estilos em tendência — Ghibli, action figure em caixa, clay 3D, pixel art, chibi e mais. Nomeie o estilo e a IA aplica a estrutura de prompt correta
Consistência multi-imagem — Tokens de design e modelos de DNA de personagem mantêm coerência visual em apresentações de slides, séries de redes sociais e ativos de marca

Os modelos de geração de imagem já possuem essas capacidades. A Skill é o que as torna acessíveis sem conhecimento especializado.

Servidor MCP vs Skill

	Servidor MCP	Skill
O que faz	Expõe ferramentas de imagem aos agentes de IA	Prompt guiado para usar as ferramentas
Funciona com	Qualquer ferramenta compatível com MCP	Claude Code, Claude Desktop
Instalação	Adicione ao `.mcp.json`	Copie os arquivos da skill para o projeto
Compartilhamento em equipe	Commit `.mcp.json` no repositório	Commit `.claude/skills/` no repositório

Recomendado: Configure o servidor MCP (Início rápido) + instale a skill se você usa Claude Code.

Ferramentas MCP

Ferramenta	Descrição
`generate_image`	Gera uma imagem a partir de um prompt de texto
`edit_image`	Edita uma imagem existente com instruções de texto
`edit_last`	Edita a última imagem gerada/editada (sem necessidade de caminho de entrada)
`undo_edit`	Desfaz a última edição, revertendo para a imagem anterior na sessão
`redo_edit`	Refaz uma edição anteriormente desfeita
`edit_history`	Mostra todas as sessões e seu histórico de edições com metadados
`switch_session`	Alterna para uma sessão de edição diferente
`clear_history`	Limpa o histórico do projeto (opcionalmente exclui arquivos de imagem)
`set_output_dir`	Altera o diretório de saída padrão (opcionalmente move arquivos existentes)
`list_providers`	Lista provedores e capacidades disponíveis

O diretório .imgx/ contém tanto o histórico de edições quanto a saída padrão de imagens. Sua localização depende da detecção da raiz do projeto:

Raiz do projeto	Localização de `.imgx/`	Histórico
Detectada	`<project-root>/.imgx/`	`<project-root>/.imgx/output-history.json`
Não detectada	`~/Pictures/imgx/` (apenas imagens)	`~/.config/imgx/output-history.json` (global)

Todos os clientes que resolvem para a mesma raiz de projeto compartilham o mesmo histórico. Cada sessão recebe seu próprio subdiretório. Os caminhos dos arquivos são retornados na resposta. A pré-visualização inline da imagem é incluída nas respostas MCP (base64).

Edição iterativa

A ferramenta edit_last usa a saída da chamada anterior de generate_image ou edit_image como entrada. Isso permite um fluxo de trabalho conversacional:

"Generate a coffee shop interior" → generate_image
"Make the lighting warmer"        → edit_last
"Add a person reading a book"     → edit_last

Sem necessidade de especificar caminhos de arquivo entre as etapas.

Gerenciamento de sessão

Cada chamada de generate_image inicia uma nova sessão. Chamadas subsequentes de edit_last são adicionadas à mesma sessão, formando uma cadeia de edições. Cada sessão tem seu próprio diretório de saída.

Desfazer / Refazer — Navegue para frente e para trás na cadeia de edições:

generate → edit_last → edit_last → edit_last
                                    ↑ current
                       ← undo_edit
                       ↑ current
                            redo_edit →
                                    ↑ current

Após desfazer, chamar edit_last cria uma ramificação a partir da posição atual (entradas abandonadas e seus arquivos são excluídos do disco).

Nomeação de arquivos — edit_last gera nomes de arquivo sequenciais com base no arquivo de origem:

generate_image             → cover.png
edit_last                  → cover-1.png
edit_last                  → cover-2.png

generate_image (no output) → imgx-a1b2c3d4.png
edit_last                  → imgx-a1b2c3d4-1.png

Alternância de sessão — Use edit_history para ver todas as sessões e depois switch_session para retomar uma sessão anterior. A ferramenta edit_last usará a posição atual na sessão alternada.

Diretório de saída — edit_last herda o diretório de saída da sessão. Se generate_image foi chamado com output_dir, todas as chamadas subsequentes de edit_last nessa sessão geram saída no mesmo diretório. O caminho output_dir é registrado como metadado da sessão em output-history.json. Isso afeta apenas onde os arquivos de imagem são salvos — o histórico permanece sempre em .imgx/ (ou no diretório de configuração global).

Configuração de chave de API

Configure pelo menos um provedor:

Gemini — obtenha uma chave no Google AI Studio (nível gratuito disponível para gemini-2.5-flash-image):

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

OpenAI — obtenha uma chave na OpenAI Platform:

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

As chaves são armazenadas em ~/.config/imgx/config.json (Linux/macOS) ou %APPDATA%\imgx\config.json (Windows). Alternativamente, passe as chaves pela seção env na sua configuração MCP, ou defina variáveis de ambiente:

export GEMINI_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"

Inclua apenas as chaves de API dos provedores que você deseja usar. Pelo menos uma é necessária.

Configuração MCP por ferramenta

Claude Code

.mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

macOS / Linux:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "imgx": {
      "command": "cmd",
      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

IMGX_PROJECT_ROOT — Defina para o caminho do seu projeto para salvar imagens dentro do projeto (ex.: "C:\\Users\\you\\my-project"). Deixe vazio para usar o padrão global (~/Pictures/imgx).

Localização do arquivo de configuração: %APPDATA%\Claude\claude_desktop_config.json (Windows) ou ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Após editar, reinicie o Claude Desktop.

Nota: O Claude Desktop não suporta detecção automática (raízes MCP / busca de .imgxrc baseada em CWD). Use IMGX_PROJECT_ROOT na configuração acima (por cliente), ou execute imgx config set project-root /path/to/project (compartilhado entre todos os clientes).

Codex CLI

.codex/config.toml:

[mcp_servers.imgx]
command = "npx"
args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }

Outras ferramentas

O mesmo padrão npx funciona com Cursor, Windsurf, Continue.dev, Cline, Zed e outras ferramentas compatíveis com MCP. No Windows, use cmd /c npx em vez de npx diretamente.

Provedores

Provedor	Modelos	Capacidades
Gemini	`gemini-2.5-flash-image` (Nano Banana — nível gratuito, padrão), `gemini-3-pro-image-preview` (Nano Banana Pro), `gemini-3.1-flash-image-preview` (Nano Banana 2)	Gerar, editar, proporção (até 14 proporções), resolução (até 4K), imagens de referência, controle de pessoas
OpenAI	`gpt-image-1`, `gpt-image-1.5` (mais rápido, 20% mais barato), `gpt-image-1-mini` (econômico)	Gerar, editar, proporção, múltiplas saídas, formato de saída (PNG/JPEG/WebP), transparência de fundo

Arquitetura

O imgx separa preocupações independentes de modelo e dependentes de modelo:

MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
 ↓                                                 ↓
Core (Capability enum, ImageProvider interface, provider registry, file I/O, history)
 ↓
Provider (model-specific API calls, capability declarations)

O servidor MCP e a CLI são dois pontos de entrada para o mesmo núcleo. Ambos chamam as mesmas funções de provedor.

Cada provedor declara suas capacidades suportadas. Adicionar um novo provedor significa implementar a interface ImageProvider e registrá-la — sem alterações na camada MCP ou CLI.

Sistema de capacidades

Capacidade	Descrição
`TEXT_TO_IMAGE`	Gera imagens a partir de prompts de texto
`IMAGE_EDITING`	Edita imagens com instruções de texto
`ASPECT_RATIO`	Controla a proporção da saída
`RESOLUTION_CONTROL`	Controla a resolução da saída
`MULTIPLE_OUTPUTS`	Gera múltiplas imagens por solicitação
`REFERENCE_IMAGES`	Usa imagens de referência para orientação
`PERSON_CONTROL`	Controla a geração de pessoas na saída
`OUTPUT_FORMAT`	Escolhe o formato de saída (PNG, JPEG, WebP)

CLI

O imgx-mcp também funciona como uma ferramenta de linha de comando autônoma.

Instalação

npm install -g imgx-mcp

Requer Node.js 18+.

Uso

# Generate
imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png

# Edit
imgx edit -i photo.png -p "Change the background to sunset" -o edited.png

# Iterative editing
imgx edit -i photo.png -p "Make the background darker"
imgx edit --last -p "Add warm lighting"
imgx edit --last -p "Crop to 16:9" -o final.png

# Undo / redo
imgx undo               # Revert to previous image in session
imgx redo               # Re-apply an undone edit

# History
imgx history            # Show all sessions and entries
imgx history switch <session-id>  # Switch to a different session
imgx history clear      # Clear project history (interactive)
imgx history clear --yes          # Clear without confirmation
imgx history clear --keep-files   # Clear history but keep image files
imgx history clear --all          # Clear ALL history across all projects

# Provider management
imgx providers          # List providers and capabilities
imgx capabilities       # Detailed capabilities of current provider

Opções da CLI

Flag	Curta	Descrição
`--prompt`	`-p`	Descrição da imagem ou instrução de edição (obrigatório)
`--output`	`-o`	Caminho do arquivo de saída (gerado automaticamente se omitido)
`--input`	`-i`	Imagem de entrada para editar (comando `edit` apenas)
`--last`	`-l`	Usa a última saída como entrada (comando `edit` apenas)
`--aspect-ratio`	`-a`	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` + Gemini 3.x: `1:4`, `1:8`, `4:1`, `4:5`, `5:4`, `8:1`, `21:9`
`--resolution`	`-r`	`1K`, `2K`, `4K`
`--count`	`-n`	Número de imagens a gerar
`--format`	`-f`	Formato de saída: `png`, `jpeg`, `webp` (apenas OpenAI)
`--background`	`-b`	Fundo: `transparent`, `opaque`, `auto` (apenas OpenAI)
`--quality`	`-q`	Qualidade: `low`, `medium`, `high`, `auto` (apenas OpenAI)
`--model`	`-m`	Nome do modelo
`--provider`		Nome do provedor (padrão: `gemini`)
`--output-dir`	`-d`	Diretório de saída

Configuração

imgx config set api-key <key> --provider gemini   # Save Gemini API key
imgx config set api-key <key> --provider openai   # Save OpenAI API key
imgx config set model <name>      # Set default model
imgx config set output-dir <dir>  # Set default output directory
imgx config set aspect-ratio 16:9 # Set default aspect ratio
imgx config set resolution 2K     # Set default resolution
imgx config list                  # Show all settings
imgx config get api-key           # Show a specific setting (API key is masked)
imgx config path                  # Show config file location

Configuração do projeto (`.imgxrc`)

Gere um modelo com imgx init:

imgx init
# → creates .imgxrc in current directory

Ou crie manualmente:

{
  "defaults": {
    "model": "gemini-2.5-flash-image",
    "outputDir": "./assets/images",
    "aspectRatio": "16:9"
  }
}

A configuração do projeto é compartilhada via Git. Não coloque chaves de API em .imgxrc.

Configuração da raiz do projeto (3 níveis)

Método	Escopo	Como definir
Variável de ambiente `IMGX_PROJECT_ROOT` na configuração do cliente	Por cliente (maior prioridade)	Adicione a `env` em `claude_desktop_config.json`, `.mcp.json`, etc.
Detecção automática (raízes MCP / busca `.imgxrc`)	Automático	Funciona em agentes CLI (Claude Code, Gemini CLI). Não disponível no Claude Desktop
`imgx config set project-root`	Todos os clientes na máquina	Armazenado na configuração do usuário (`~/.config/imgx/config.json` ou `%APPDATA%\imgx\config.json`)

Prioridade de detecção: variável de ambiente → raízes MCP → busca ascendente .imgxrc → configuração do usuário projectRoot.

O histórico é salvo em <project-root>/.imgx/output-history.json (escopo do projeto, não compartilhado com outros projetos). A saída padrão de imagens vai para <project-root>/.imgx/<session-id>/. Caminhos relativos em output e output_dir são resolvidos em relação à raiz do projeto, em vez do diretório de trabalho do servidor MCP.

Resolução de configurações

Flags de CLI (--model, --output-dir, etc.)
Variáveis de ambiente (IMGX_MODEL, IMGX_OUTPUT_DIR, etc.)
Configuração do projeto (.imgxrc — pesquisada a partir do diretório atual para cima)
Configuração do usuário (~/.config/imgx/config.json ou %APPDATA%\imgx\config.json)
Padrões do provedor

Formato de saída

Todos os comandos CLI geram JSON:

{"success": true, "filePaths": ["./output.png"]}

Plugin Claude Code

O plugin agrupa servidor MCP + skill em uma única etapa. Se você preferir não configurar .mcp.json e arquivos de skill manualmente:

/plugin marketplace add somacoffeekyoto/imgx-mcp
/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp

Atualização: /plugin → instalado → imgx-mcp → atualizar. Se a atualização não mostrar alterações, desinstale e reinstale.

Desinstalação: /plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp e depois /plugin marketplace remove somacoffeekyoto-imgx-mcp.

Desenvolvimento

git clone https://github.com/somacoffeekyoto/imgx-mcp.git
cd imgx-mcp
npm install
npm run bundle    # TypeScript compile + esbuild bundle

A compilação produz dois bundles:

dist/mcp.bundle.js — ponto de entrada do servidor MCP
dist/cli.bundle.js — ponto de entrada da CLI

Desinstalação

Servidor MCP

Remova a entrada imgx do arquivo de configuração MCP da sua ferramenta.

Skill

Exclua o diretório image-generation/ de .claude/skills/ ou ~/.claude/skills/.

CLI

npm uninstall -g imgx-mcp

npm uninstall remove o pacote, mas não exclui arquivos de configuração ou gerados. Remova-os manualmente se necessário:

Configuração global:

# Linux / macOS
rm -rf ~/.config/imgx/

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\imgx"

Histórico e imagens do projeto: Cada projeto pode ter um diretório .imgx/ contendo histórico de edições e imagens geradas. Remova-o de cada projeto conforme necessário.

rm -rf <project-root>/.imgx/

Licença

MIT — SOMA COFFEE KYOTO

imgx-mcp

Documentação

imgx-mcp

O que diferencia o imgx-mcp

Início rápido

Skill (Claude Code)

Instalar a skill

Claude Desktop

O que a Skill oferece

Servidor MCP vs Skill

Ferramentas MCP

Edição iterativa

Gerenciamento de sessão

Configuração de chave de API

Configuração MCP por ferramenta

Claude Code

Gemini CLI

Claude Desktop

Codex CLI

Outras ferramentas

Provedores

Arquitetura

Sistema de capacidades

CLI

Instalação

Uso

Opções da CLI

Configuração

Configuração do projeto (.imgxrc)

Configuração da raiz do projeto (3 níveis)

Resolução de configurações

Formato de saída

Plugin Claude Code

Desenvolvimento

Desinstalação

Servidor MCP

Skill

CLI

Licença

Links

Configuração do projeto (`.imgxrc`)