photoshop-mcp

Photoshop MCP Server

Idiomas: English · 简体中文 · Español · Deutsch · 日本語 · Türkçe · Website

v1.1+ — fluxos de trabalho com receitas, menos idas e voltas, sessões mais ágeis. A UI autônoma inclui Action Plan (beta) para execuções de planejar-depois-executar.

Nota: Este é um projeto não oficial, mantido pela comunidade, e não é afiliado ou endossado pela Adobe Inc.

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA como Claude e Cursor controlem o Adobe Photoshop programaticamente. Isso permite criar designs, manipular imagens e automatizar fluxos de trabalho do Photoshop por meio de comandos em linguagem natural enquanto você trabalha na sua IDE — ou pela UI web autônoma incluída, que suporta tanto chaves de API quanto contas de assinatura CLI (Claude Code / Gemini CLI). A UI também oferece um modo Action Plan (beta) opcional que planeja cada etapa do Photoshop em uma única chamada de LLM e depois as executa em uma única passada.

Por que isso existe

Designers e desenvolvedores querem controlar o Photoshop a partir de assistentes de IA, mas chamadas ExtendScript brutas são frágeis: agentes desperdiçam tokens em tentativa e erro, tipos de camada quebram filtros, e um comando com falha deixa o documento em um estado desconhecido.

O Photoshop MCP adiciona consciência de estado (get_state, get_preview, get_capabilities), ferramentas de receita que encapsulam resultados de múltiplas etapas em um único passo de desfazer, e envelopes de erro estruturados para que os agentes saibam o que tentar em seguida. A UI autônoma opcional e o modo Action Plan reduzem idas e voltas para fluxos de trabalho mais longos — para que a linguagem natural possa realmente entregar pixels, não apenas sugeri-los.

Mergulho técnico: docs/architecture.md.

🖥️ UI autônoma (sem necessidade de IDE)

Não quer integrar isso ao Claude Desktop ou Cursor? O mesmo pacote inclui uma UI web totalmente local que permite conversar com um modelo de IA e controlar o Photoshop por meio deste servidor MCP por baixo dos panos. Conecte-se com uma chave de API do provedor ou, para Anthropic e Google, reutilize a sessão OAuth do Claude Code ou Gemini CLI — sem necessidade de chave de API separada.

npx -p @alisaitteke/photoshop-mcp photoshop-mcp-ui

É isso. Um servidor local inicia em 127.0.0.1 (porta livre aleatória) e seu navegador padrão abre a UI de chat automaticamente.

Provedores suportados

Escolha qualquer um dos seguintes na primeira inicialização — use uma chave de API ou sua conta de assinatura CLI existente (Anthropic e Google):

Modos de autenticação

• api_key (padrão) — Vercel AI SDK + sua chave de API do provedor. O uso é cobrado por token nas tarifas da API; a UI mostra o custo estimado por chat.
• cli_account — Usa sua sessão OAuth local do Claude Code ou Gemini CLI. Nenhuma chave de API é armazenada; a UI verifica claude auth status / gemini headless para confirmar o login. O uso conta contra sua cota de assinatura, não a cobrança da API — a barra de status mostra "Incluído na assinatura".

Você pode alternar o método de autenticação por provedor nas Configurações sem perder a outra credencial (ex.: manter uma chave de API enquanto testa a conta CLI e depois voltar).

Action Plan (beta)

Um modo de execução opcional na UI web autônoma somente para autenticação por chave de API (cli_account sempre usa o fluxo agêntico padrão). Ative-o com o alternador Action Plan ao lado do seletor de modelo no compositor.

Em vez de um loop ReAct por etapa (modelo → ferramenta → modelo → ferramenta …), o Action Plan:

1. Faz uma chamada de planejamento ao LLM que gera uma lista ordenada de tarefas com chamadas de ferramentas do Photoshop MCP e parâmetros.
2. Executa essas ferramentas diretamente em sequência — sem idas e voltas extras ao modelo entre as etapas.
3. Em caso de etapa com falha ou dependência não resolvida, executa um loop de reparo limitado (replaneja apenas as etapas restantes, até 3 vezes).

O plano aparece como uma lista de tarefas ao vivo acima dos cartões de chamadas de ferramentas, com status por etapa (pending → running → done / error). Os planos são persistidos no histórico do chat para sobreviverem ao recarregamento. O alternador fica desligado por padrão; o fluxo agêntico existente permanece inalterado quando o Action Plan está desativado.

Bom para prompts de múltiplas etapas como "remover o fundo e exportar para web" em que você quer menos chamadas ao modelo e execução ponta a ponta mais rápida.

O que acontece na primeira inicialização

1. Escolha um provedor e selecione API key ou Usa sua conta.
2. Valide a chave ou verifique a conexão CLI. A configuração é armazenada localmente em ~/.photoshop-mcp/data.db (SQLite, chmod 600). As chaves de API nunca saem da sua máquina; o modo CLI herda o OAuth de ~/.claude/ ou ~/.gemini/.
3. Digite prompts em linguagem natural. A UI transmite a resposta do modelo, executa chamadas de ferramentas do Photoshop em tempo real e renderiza cada chamada como um cartão inspecionável (entrada + resultado).
4. Alterne provedor, método de autenticação ou modelo a qualquer momento pelas Configurações / seletor de modelo — chats, custos e histórico de ferramentas são persistidos entre sessões.

Alterando o método de autenticação depois

Abra Configurações pela barra lateral a qualquer momento:

O método de autenticação é armazenado por provedor em ~/.photoshop-mcp/data.db (authMethod: api_key ou cli_account). Configurações existentes sem authMethod usam api_key por padrão e continuam funcionando sem alterações.

Flags da CLI

photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]

Segurança da API local

O servidor da UI armazena suas chaves de API do provedor e pode controlar o Photoshop, então /api/* não fica aberto para tudo que roda na sua máquina. Cada requisição deve passar por três verificações:

1. Host — deve ser o endereço de loopback (ou o --host ao qual você vinculou) na porta do servidor. Bloqueia rebinding de DNS.
2. Origin — quando presente, deve corresponder à origem da própria UI. Bloqueia chamadas de navegador entre origens.
3. Token de sessão — um segredo aleatório por inicialização. Bloqueia outros processos locais, que podem forjar qualquer cabeçalho, mas não conseguem ler o token.

O navegador nunca precisa lidar com o token: o servidor o injeta no index.html que ele serve. Para scripts, leia-o de ~/.photoshop-mcp/ui-session.json (chmod 600) e envie-o como x-psmcp-token ou Authorization: Bearer, ou defina o seu próprio com PSMCP_UI_TOKEN antes de iniciar o servidor. Requisições sem token válido recebem 401 unauthorized.

Notas

• O agente é restrito apenas às ferramentas do Photoshop MCP — ferramentas integradas de shell, arquivo e web são desativadas.
• Stack tecnológico: Vue 3 + Tailwind v4 + shadcn-vue no frontend; Hono no backend. O modo chave de API usa o Vercel AI SDK; o modo conta CLI usa o Claude Agent SDK (Anthropic) ou Gemini CLI headless stream-json (Google). Todos os caminhos falam com este mesmo servidor Photoshop MCP via STDIO.
• Limitações da conta CLI: o Gemini headless pode abrir uma nova sessão a cada turno (o histórico é anexado ao início do prompt). A conta CLI da Anthropic consome cota da assinatura. O login OAuth é priorizado para macOS (claude auth login / gemini auth login no Terminal).

Camada de IA/Prompt para o Photoshop

Além das ferramentas atômicas photoshop_*, o servidor inclui uma camada opinativa de IA/prompt que ajuda LLMs hospedeiros (Cursor, Claude Desktop, etc.) a traduzir solicitações vagas dos usuários em ações confiáveis no Photoshop:

• instructions do servidor — contrato de fluxo de trabalho anunciado no MCP initialize (ping uma vez, estado antes da ação, prefira receitas, recuperação de erros). Veja src/prompts/instructions.ts.
• Primitiva MCP prompts — 23 modelos pré-construídos (16 receitas + 7 guias: ps.enhance_portrait, ps.remove_background, ps.generative_fill, …) via prompts/list e prompts/get.
• Ferramentas de receita — 16 ferramentas photoshop_recipe_* orientadas a resultados (remover fundo, aprimorar retrato, preparar para web, exportar variantes para redes sociais, color grading, separação de frequência, mockup em lote, organizar camadas, fade gradiente, mistura de céu, dodge & burn, remover distração, dividir carrossel, marca d'água em lote, foto para passaporte, csv para cards). Cada uma encapsula as etapas em um único estado de histórico do Photoshop (um Desfazer reverte tudo). 102 ferramentas no total (86 atômicas + 16 receitas).
• IA generativa — photoshop_generative_fill, photoshop_generative_remove, photoshop_generative_expand, photoshop_generative_upscale, photoshop_sky_replacement, photoshop_generate_image (Firefly via ExtendScript; conta Adobe + créditos necessários).
• Filtros neurais — photoshop_neural_filter via plugin de ponte UXP opcional (uxp-plugin/): suavização de pele, harmonizar, desfoque de profundidade, super zoom e colorização (P&B → cor).
• Estado e pré-visualização — photoshop_get_state (snapshot barato), photoshop_get_preview (JPEG base64 para verificação por visão), photoshop_get_capabilities (feature flags cientes da versão).
• Erros estruturados — falhas retornam envelopes JSON com code e suggested_next_tool para autocorreção.

Referência completa: docs/prompt-layer.md.

Verifique a paridade: npm run verify:photoshop-prompts. Resultados mais recentes: docs/development.md#integration-test-results.

Exemplos de Prompts

Abaixo estão exemplos de prompts que você pode usar com assistentes de IA (Claude, Cursor, etc.) quando este servidor MCP estiver configurado. Prefira ferramentas de receita (photoshop_recipe_*) para resultados de múltiplas etapas — cada receita é um único passo de desfazer. Use ferramentas atômicas photoshop_* apenas para edições de granularidade fina que nenhuma receita cobre.

Ping Photoshop and read capabilities for my installed version.
Get the current document state before changing anything.
Open portrait.jpg, get a downscaled preview so you can verify the subject.
After each major recipe, get another preview to confirm the result.

Receitas

Cada receita encapsula um resultado de múltiplas etapas em um único passo de desfazer e mapeia 1:1 para um modelo de prompt ps.*.

✂️ Remoção de fundo

Remove the background from the active portrait layer.
Use Select Subject + a layer mask with a 2px feather. Keep the original pixels behind the mask.
The subject must be on the active layer — not a flat color fill.

Modelo de prompt MCP equivalente: ps.remove_background com { feather_px: "2", keep_shadow: "false" }.

🧹 Remover distração

There's a tourist photobombing my landscape on the active layer.
I'll rough-select him with the lasso — then run the remove-distraction recipe with a 1px feather.
Content-aware fill only; don't touch anything outside the selection.

Modelo de prompt MCP equivalente: ps.remove_distraction com { feather_px: "1" }.

👤 Retoque de retrato

Enhance the portrait on the active layer at medium intensity with skin smoothing.
Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
Show me a preview when done.

Modelo de prompt MCP equivalente: ps.enhance_portrait com { intensity: "medium", skin_smoothing: "true" }.

🔥 Dodge & burn

Set up dodge & burn on the active portrait layer: a 50% gray layer in overlay blend mode.
I'll paint with a white/black brush myself — just prepare the non-destructive setup.

Modelo de prompt MCP equivalente: ps.dodge_burn com { blend_mode: "overlay" }.

🔬 Configuração de separação de frequência

Set up frequency separation on the active raster layer with a 6px blur radius.
I will paint on the Low and High layers myself — do not apply extra smoothing.
Tell me which layers to edit when the stack is ready.

Modelo de prompt MCP equivalente: ps.frequency_separation com { radius_px: "6" }.

🌗 Fade gradiente

Fade the isolated subject into the background from the bottom up.
Apply a bottom_to_top gradient on the layer mask, 0 to 100%. Keep the mask editable.

Modelo de prompt MCP equivalente: ps.gradient_fade com { direction: "bottom_to_top" }.

🌤️ Mistura de céu

The sky in my landscape is blown out. Blend ~/skies/sunset.jpg in as the new sky,
horizon at 45% of the frame height, feathered so the treeline stays natural.

Modelo de prompt MCP equivalente: ps.sky_blend com { sky_image_path: "~/skies/sunset.jpg", horizon_pct: "45" }.

🎨 Color grading

Apply a warm film color grade to the open document as non-destructive adjustment layers.
Use the apply-color-grade recipe with preset warm_film.
Preview the result when finished.

Modelo de prompt MCP equivalente: ps.apply_color_grade com { preset: "warm_film" }.

🌐 Preparar para web + exportação para redes sociais

Prepare the active document for web: sRGB, downscale, sharpen, export one optimized JPEG to ~/.photoshop-mcp/exports.
Then export Instagram post and X post variants as separate JPEGs from the same document.
List the output paths in a table.

Modelos equivalentes: ps.prepare_for_web, ps.export_social_variants.

📦 Substituição em lote de mockups

I have a mockup PSD open with a Smart Object layer named "Screen".
Replace it with every PNG/JPG in ~/assets/mockups/ and export one JPEG per asset.
Do not place flat layers — swap the Smart Object so perspective is preserved.

Modelo de prompt MCP equivalente: ps.batch_mockup_replace.

🗂️ Organizar camadas

Organize the layer stack: rename by kind, auto-group related layers, preserve originals.
Run the organize-layers recipe, then list layers so I can review the new structure.

Modelo de prompt MCP equivalente: ps.organize_layers.

🎞️ Divisão de carrossel contínuo

Split the active document into a 5-slide seamless Instagram carousel.
Each slide should be 1080x1350 — crop the slices, don't letterbox them.
Give me the exported file paths in swipe order so I can upload them as-is.

Modelo de prompt MCP equivalente: ps.split_carousel com { slides: "5", size: "1080x1350" }.

💧 Marca d'água em lote

Watermark every photo in ~/photos/portfolio with the text "© Jane Doe 2026".
Bottom-right corner, 40% opacity, small margin from the edges.
Export watermarked JPEGs — never touch the originals.

Modelo de prompt MCP equivalente: ps.batch_watermark com { assets_dir: "~/photos/portfolio", text: "© Jane Doe 2026", position: "bottom_right", opacity: "40" }.

🛂 Foto para passaporte / documento de identidade

Turn the open portrait into a US passport photo: white background, proper headroom,
exact 600x600 px at 300 DPI. Also give me a 10x15 cm print sheet with copies.
Note: framing is approximated from subject bounds — official acceptance is not guaranteed.

Modelo de prompt MCP equivalente: ps.passport_photo com { spec: "us_2x2", make_sheet: "true" }.

🪪 CSV → cartões (gráficos orientados por dados)

Generate a name card for every row in ~/cards/speakers.csv using the open template PSD.
PNG output to ~/cards/out — one file per row, named after the row.

Modelo de prompt MCP equivalente: ps.csv_to_cards com { csv_path: "~/cards/speakers.csv", output_dir: "~/cards/out", format: "PNG" }.

Mais exemplos

Create a 1920x1080 Photoshop document with RGB color mode.
Add a light blue background layer and fill it with RGB(240, 248, 255).
Add centered text "Welcome" in 64pt font.
Save as welcome.psd to my Desktop.

Search Pexels for "mountain sunset" images.
Create a 1920x1080 Photoshop document.
Place the downloaded image and fit it to fill the entire canvas.
Apply a subtle Gaussian blur of 3px.
Increase brightness by 15 and contrast by 10.
Add white text "Adventure Awaits" centered at the top in 72pt.
Set the text opacity to 90% and blend mode to OVERLAY.
Save as adventure.jpg with quality 10.

Open photo.jpg from my Desktop in Photoshop.
Get state, then run the enhance-portrait recipe at low intensity.
If I only need quick tone fixes, apply auto levels, auto contrast, and unsharp mask (120%, 1.5, 0) on the active layer instead.
Adjust hue +15 and saturation +15, or use prepare-for-web when I'm ready to export.
For old black-and-white scans, run the colorize neural filter first (requires the UXP bridge plugin).
Save as enhanced-photo.jpg with quality 12.

Create a 1200x800 document.
Add a new layer named "Background" and fill with RGB(50, 50, 50).
Place logo.png at position (100, 100).
Fit the logo layer to 50% of its current size.
Set blend mode to SCREEN and opacity to 85%.
Add another layer, fill with RGB(255, 100, 50).
Set this layer's blend mode to MULTIPLY and opacity to 60%.
Merge all visible layers.
Save as composite.psd.

Create a 1080x1350 portrait document (Instagram story size).
Add a layer and fill with gradient-like color RGB(120, 40, 200).
Add text "SUMMER" at (540, 300) in 96pt.
Change text color to white RGB(255, 255, 255).
Set text alignment to CENTER.
Add another text "2026" at (540, 450) in 128pt, white color.
Apply Gaussian blur 2px to the background layer.
Save as summer-poster.png.

Open image1.jpg.
Resize to 1920x1080.
Apply auto contrast.
Apply subtle sharpen (amount 80%, radius 1.0).
Save as processed-1.jpg with quality 10.
Close without saving changes to original.

Repeat for image2.jpg and image3.jpg.

Create a 2000x2000 square document.
Place abstract-pattern.jpg and fit to fill document.
Duplicate the layer.
On the duplicate, apply motion blur at 45 degrees, radius 50px.
Set blend mode to OVERLAY and opacity to 70%.
Add centered text "MOTION" in 120pt white.
Apply a rectangular selection from (200, 200) to (1800, 1800).
Invert the selection and delete (to create a border effect).
Flatten the image.
Save as motion-art.jpg.

Create a 3000x2000 document at 300 DPI for print.
Place hero-image.jpg and fit to fill the canvas.
Duplicate the image layer.
On the duplicate, desaturate it completely.
Set blend mode to LUMINOSITY and opacity to 50%.
Create a new layer named "Overlay".
Fill with RGB(255, 150, 0) and set blend mode to SOFTLIGHT at 30% opacity.
Add text "PORTFOLIO" at top center (1500, 200) in 96pt.
Set text color to white.
Add subtext "2026 Collection" at (1500, 320) in 36pt.
Create a rectangular selection around the text area.
Create a layer mask on the overlay layer.
Merge visible layers.
Save as portfolio-cover.psd.
Export as portfolio-cover.jpg at quality 12.

Open my-photo.jpg.
Play the "Vintage Look" action from "My Actions" set.
Adjust brightness by -10 to darken slightly.
Save as vintage-photo.jpg.

Execute this custom ExtendScript code:
app.beep();
alert('Processing started!');

Apply Gaussian blur 15px to the active layer.
[Wait for result]
Actually, that's too much blur. Undo that.
Apply Gaussian blur 5px instead.

Get the history states to see what operations were performed.
Undo the last 3 operations.
Redo 1 step to bring back one operation.

If a recipe returns version_unsupported or generative_unavailable, call get_capabilities and tell me which Photoshop feature is missing.
If a tool fails with suggested_next_tool, follow that hint (e.g. rasterize_layer before a raster-only recipe).
Never guess — read get_state after a failure and propose the next single step.

Recursos

• Interface web independente — interface de chat local (photoshop-mcp-ui); autenticação por API key ou CLI por provedor (Anthropic, Google)
• Plano de ação (beta) — modo opcional de planejar-e-executar na interface web (somente API key): uma chamada de planejamento, execução direta de ferramentas, reparo limitado em caso de falha
• Funciona em Windows e macOS
• Suporta Photoshop 2012-2025+
• API ExtendScript: Compatibilidade universal via automação AppleScript/COM
• Detecção automática: Encontra automaticamente a instalação do Photoshop no seu sistema
• 102 ferramentas: 86 photoshop_* atômicos + 16 photoshop_recipe_* de receita
• Camada de IA/prompt: 23 modelos de prompt MCP (16 receitas + 7 guias), instruções do servidor, ferramentas de estado/visualização/capacidades
• Gerenciamento de documentos: Criar, abrir, salvar, fechar, recortar documentos
• Operações de camada: Criar, excluir, duplicar, mesclar, transformar camadas
• Propriedades de camada: Opacidade, modos de mesclagem, visibilidade, bloqueio
• Estilos de camada: Sombra projetada, brilho externo, traço, chanfro e relevo
• Formatação de texto: Controles de fonte, tamanho, cor, alinhamento
• Inserção de imagens: Inserir imagens, abrir arquivos, ajustar ao documento
• Filtros: Desfoque gaussiano, nitidez, ruído, desfoque de movimento
• Ajustes de cor: Brilho/Contraste, Matiz/Saturação, Curvas, Níveis automáticos/Contraste automático
• Graduação de cor: Camadas de LUT 3D (Color Lookup), Vibrância, Exposição, Filtro de foto, Mapa de gradiente
• Gráficos orientados por dados: CSV/XML de variáveis → uma imagem por linha ("mala direta para imagens")
• Empilhamento de imagens: Modos de empilhamento média/mediana para remoção de turistas e redução de ruído
• Exportação moderna: PNG/JPEG além de WebP/AVIF (nativo, PS 23.2+)
• Seleções e máscaras: Seleções retangulares, selecionar assunto, preenchimento com base no conteúdo, máscara de gradiente, máscaras de camada
• Controle de histórico: Operações de desfazer/refazer, visualizar estados de histórico
• Ações: Reproduzir ações gravadas, executar scripts personalizados
• Rasterização automática: Converte camadas automaticamente quando necessário para filtros
• Rastreamento de contexto: Retorna o estado do documento/camada após cada operação para conscientização de contexto da IA

Instalação

Instalação com um clique

Ou a partir de um terminal — Claude Code:

claude mcp add photoshop -- npx -y @alisaitteke/photoshop-mcp

Usando NPX (recomendado)

Nenhuma instalação necessária! Basta configurar seu cliente MCP:

npx @alisaitteke/photoshop-mcp

Para desenvolver no repositório localmente, consulte A partir do código-fonte no guia de desenvolvimento.

Configuração

Para Cursor

Adicione às configurações do Cursor (.cursor/config.json ou configurações do workspace):

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "LOG_LEVEL": "1"
      }
    }
  }
}

Para Claude Desktop

Adicione à configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "LOG_LEVEL": "1"
      }
    }
  }
}

Não consegue encontrar o arquivo de configuração? No Claude Desktop, abra Configurações → Desenvolvedor → Editar configuração — ele abre o caminho correto para sua instalação (o caminho %APPDATA% pode diferir em algumas configurações).

Para Claude Code

Use o CLI do Claude Code ou o SDK do Claude Agent com a mesma entrada de servidor MCP.

Recomendado (CLI):

claude mcp add photoshop -- npx -y @alisaitteke/photoshop-mcp

JSON manual — mescle no seu .mcp.json do projeto ou nas configurações MCP do Claude Code (consulte examples/claude-code-mcp.json):

{
  "mcpServers": {
    "photoshop": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/photoshop-mcp"],
      "env": {
        "LOG_LEVEL": "1"
      }
    }
  }
}

SDK do agente (TypeScript) — passe o mesmo bloco mcpServers nas opções do seu query():

import { query } from '@anthropic-ai/claude-agent-sdk';

const q = query({
  prompt: 'List open documents in Photoshop',
  options: {
    mcpServers: {
      photoshop: {
        command: 'npx',
        args: ['-y', '@alisaitteke/photoshop-mcp'],
        env: { LOG_LEVEL: '1' },
      },
    },
    allowedTools: ['mcp__photoshop__*'],
  },
});

Variáveis de ambiente

• PHOTOSHOP_PATH: (Opcional) Especifique o caminho de instalação personalizado do Photoshop
• LOG_LEVEL: Nível de registro (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR)
• ANALYTICS_DISABLED: Defina como 1 ou true para desativar completamente a análise de uso anônima
• POSTHOG_DISABLED: Alias legado para ANALYTICS_DISABLED
• ANALYTICS_PROVIDER: Backend de análise — mixpanel (padrão) ou posthog (rollback)
• MIXPANEL_TOKEN: (Opcional) Substituir o token do projeto Mixpanel
• MIXPANEL_API_HOST: (Opcional) Host de ingestão do Mixpanel (padrão: https://api-eu.mixpanel.com)
• POSTHOG_KEY: (Opcional, legado) Chave do projeto PostHog — usada somente quando ANALYTICS_PROVIDER=posthog
• POSTHOG_API_HOST: (Opcional, legado) Host de ingestão do PostHog (padrão: https://a.alisait.com)
• POSTHOG_UI_HOST: (Opcional, legado) Host da interface do PostHog (padrão: https://eu.posthog.com)

Ferramentas disponíveis

Referência completa para todas as ferramentas photoshop_* atômicas (parâmetros, exemplos e uso): docs/available-tools.md.

Rastreamento de contexto

Cada ferramenta retorna informações abrangentes de contexto sobre o estado atual do Photoshop, incluindo:

• Informações do documento: Nome, dimensões, resolução, modo de cor, contagem de camadas
• Informações da camada ativa: Nome, tipo, opacidade, modo de mesclagem, visibilidade, estado de bloqueio
• Estado da seleção: Se uma seleção está ativa
• Resultado da operação: Detalhes específicos sobre o que foi alterado

Isso permite que assistentes de IA mantenham a consciência de:

• Qual documento está ativo
• Em qual camada está sendo trabalhada
• Propriedades atuais da camada (opacidade, modos de mesclagem, etc.)
• Dimensões e configurações do documento

Exemplo de resposta:

{
  "applied": true,
  "filter": "Gaussian Blur",
  "radius": 10,
  "wasRasterized": true,
  "context": {
    "hasDocument": true,
    "document": {
      "name": "design.psd",
      "width": 1920,
      "height": 1080,
      "resolution": 72,
      "colorMode": "RGBColorMode",
      "layerCount": 3,
      "hasSelection": false
    },
    "activeLayer": {
      "name": "Background",
      "kind": "NORMAL",
      "opacity": 100,
      "blendMode": "NORMAL",
      "visible": true,
      "locked": false,
      "isBackground": false
    }
  }
}

Esse contexto ajuda os assistentes de IA a lembrar em qual documento e camada estão trabalhando em vários comandos.

Notas específicas da plataforma

Windows

• Usa automação COM para se comunicar com o Photoshop
• Detecção automática baseada no registro para caminhos de instalação
• Suporta versões de 32 bits e 64 bits

macOS

• Usa AppleScript/OSA para comunicação com o Photoshop
• Detecção automática baseada em Spotlight
• Suporta várias versões do Photoshop instaladas simultaneamente
• Autenticação de conta CLI (interface independente) é prioridade no macOS: execute claude auth login / gemini auth login no Terminal; as credenciais ficam em ~/.claude/ e ~/.gemini/

Versões suportadas do Photoshop

• Todas as versões do Photoshop (2012-2025+): Usa a API ExtendScript via AppleScript (macOS) ou COM (Windows)

Nota importante: Embora o Photoshop 2022+ suporte UXP para plugins, a automação externa via AppleScript/COM só pode usar ExtendScript. O UXP é projetado para plugins internos e não pode ser invocado a partir de scripts externos. Portanto, este servidor MCP usa ExtendScript para máxima compatibilidade em todas as versões do Photoshop.

Solução de problemas

Problemas comuns de conexão, script e registro: docs/troubleshooting.md.

Interface independente — autenticação de conta CLI

Desenvolvimento

Configuração a partir do código-fonte, build, lint, testes de integração (com resultados mais recentes) e exemplos de uso: docs/development.md.

Arquitetura

Design do sistema, fluxo de dados, abstração de plataforma e modos de agente da interface: docs/architecture.md.

Compartilhando no LinkedIn ou redes sociais? Use images/og-social.png e docs/social-preview.md para configuração de OG e texto da postagem.

Contribuindo

Contribuições são bem-vindas! Leia CONTRIBUTING.md antes de abrir um PR.

Sobre o mantenedor

Ali Sait Teke — Engenheiro Full-Stack e arquiteto de software da era da IA (Python, Go, Node.js, React, Next.js, Vue).

Este projeto começou com uma pergunta prática: como tornar o Photoshop controlável de forma confiável por LLMs sem scripts frágeis e descartáveis? Ele cresceu para um servidor MCP com 80 ferramentas, uma camada de receitas/prompts para fluxos de trabalho confiáveis em várias etapas, e uma interface web local para que o trabalho criativo não exija um IDE.

O que este código demonstra: Design de sistemas TypeScript, integração de protocolo MCP, automação de desktop multiplataforma (AppleScript no macOS / COM no Windows), recuperação estruturada de erros para loops de agentes, e uma interface local-first voltada para produção (Vue 3 + Hono + SQLite).

• Portfólio · GitHub · LinkedIn

Licença

MIT

Análise de uso anônima

Eventos de uso anônimos e agregados são coletados por padrão para melhorar o produto. Você pode desativar a qualquer momento. Detalhes completos: docs/anonymous-usage-analytics.md.

Agradecimentos

• Construído com o Model Context Protocol SDK
• Inspirado pela comunidade de scripts do Adobe Photoshop