AutomateLab n8n

n8n-mcp

Um servidor MCP para n8n que fornece a Claude, Cursor e outros agentes de IA ferramentas para gerar fluxos de trabalho, fazer lint, diagnosticar execuções com falha e operar instâncias n8n ao vivo.

Por que construímos isso

Usamos n8n diariamente dentro da AutomateLab e continuamos encontrando as mesmas falhas de LLM: JSON de fluxo de trabalho que importa mas falha em tempo de execução, clusters de Agente de IA conectados com tipos de conexão errados, execuções que silenciosamente descartam itens sem pista de onde procurar. Despejar todo o catálogo n8n no contexto não resolve - os modos de falha são sutis demais (incompatibilidades de typeVersion, esquema IF v1, credenciais que não sobrevivem à importação).

Então construímos um servidor pequeno e focado: codificar os modos de falha que o lint pode capturar, a topologia de cluster que o gerador deve respeitar e o diagnóstico que o agente não consegue fazer sozinho. Para um passo a passo das nove ferramentas com exemplos de saída, veja o post de lançamento em automatelab.tech.

Por que é diferente

Outros servidores MCP n8n (notavelmente czlonkowski/n8n-mcp) competem em amplitude - 20+ ferramentas e um corpus indexado de cada nó n8n. Eles dominam esse nicho.

Este servidor é o MCP de depuração e correção de primeira execução para n8n:

• execution_explain é a cunha. Cole o JSON de execução; receba de volta descobertas por nó: quais nós retornaram 0 itens, quais tiveram expressões ={{ ... }} não resolvidas, mensagens de erro com dicas concretas. Nenhum outro servidor MCP faz isso bem, e isso atinge o ponto de dor nº 1 da comunidade n8n (perda silenciosa de dados entre nós).
• workflow_generate é opinativo sobre a topologia do Agente de IA - emite clusters LangChain adequados com conexões ai_languageModel / ai_memory / ai_tool (sub-nós conectam para cima ao agente, não via main). Importa limpo no n8n 1.x.
• workflow_lint captura as falhas silenciosas: tipos de nó obsoletos (Function → Code, spreadsheetFile → convertToFile), Agente de IA sem modelo de linguagem, esquema IF v1, Webhook sem webhookId, conexões quebradas em todos os tipos de conexão (não apenas main).
• 5 ferramentas REST (controladas por N8N_API_URL + N8N_API_KEY) permitem listar, buscar, criar, ativar fluxos de trabalho e puxar execuções - para que as ferramentas de lint e explicação possam rodar contra seus fluxos de trabalho ao vivo, não apenas JSON colado no chat.

Além disso: uma Agent Skill emparelhada que ensina o modelo quando usar qual ferramenta e onde carregar contexto mais profundo (dividida em references/ para não inchar o prompt).

Ferramentas

Os nomes das ferramentas seguem notação de ponto e formam uma árvore navegável: node.*, workflow.*, execution.*. Cada ferramenta declara um outputSchema (para que os chamadores possam verificar tipos nas respostas) e MCP annotations (dicas somente leitura / destrutivas / idempotentes / mundo aberto).

Sem estado (funcionam sem uma instância n8n ao vivo):

Ferramenta	Propósito
workflow_generate	Descrição em inglês simples → JSON de fluxo de trabalho. Detecta intenção de agente de IA.
node_scaffold	Descrição → arquivo TypeScript INodeType único para um pacote n8n personalizado.
workflow_lint	JSON de fluxo de trabalho → lista de erros e avisos (20+ regras).
workflow_diff	Dois fluxos de trabalho → diff semântico (nós adicionados/removidos/modificados, conexões, configurações).
execution_explain	JSON de execução com falha → diagnóstico por nó com dicas.
execution_replay	Fluxo de trabalho + nó → fluxo de trabalho de replay autocontido que exercita apenas esse nó.
execution_timeline	JSON de execução → tabela de linha do tempo por nó (início, duração, itens entrada/saída, erros).

Instância ao vivo (exigem variáveis de ambiente N8N_API_URL + N8N_API_KEY):

Ferramenta	Propósito
workflow_list	Paginar fluxos de trabalho; filtrar por ativo/tags/nome.
workflow_get	Buscar um fluxo de trabalho por id.
workflow_create	Enviar um fluxo de trabalho via POST. Remove campos somente leitura.
workflow_activate	Alternar ativo/desativado.
execution_list	Navegar por execuções; passe includeData: true para o corpo completo.

Mudanças na v0.5.0. Três novas ferramentas: workflow_diff, execution_replay, execution_timeline. Lint expandido com 10 novas regras (rate-limit, desvio de credenciais, obsolescência de expressões, sandbox de código, caminho de teste de webhook, manualTrigger-em-ativo, risco de agendamento DST, desativado-mas-conectado, Set vazio, incompatibilidade de método/corpo HTTP). Novas variáveis de ambiente de política de runtime: N8N_MCP_READ_ONLY, N8N_MCP_DISABLED_TOOLS, N8N_MCP_ALLOWED_WORKFLOW_IDS, N8N_MCP_ALLOWED_TAGS. Pacote DXT + Dockerfile + configurações de deploy Render/Railway/Fly.

Mudança que quebra na v0.4.0. As ferramentas foram renomeadas de n8n_* (snake_case) para notação de ponto. Atualize quaisquer prompts, skills de agente ou scripts que referenciam os nomes antigos.

Política de runtime (v0.5+)

Restrinja o servidor sem fazer fork. Defina estas variáveis de ambiente antes de iniciar:

Variável de ambiente	Efeito
N8N_MCP_READ_ONLY=1	Desativa workflow_create, workflow_activate, node_scaffold.
N8N_MCP_DISABLED_TOOLS=workflow_create,workflow_activate	Pula completamente o registro dessas ferramentas.
N8N_MCP_ALLOWED_WORKFLOW_IDS=abc,def	As ferramentas REST se recusam a tocar em qualquer fluxo de trabalho fora da lista.
N8N_MCP_ALLOWED_TAGS=prod,staging	workflow_list filtra para fluxos de trabalho que possuem pelo menos uma tag.

Útil ao entregar o MCP a um agente júnior ou conectá-lo atrás de um assistente voltado ao cliente.

Implantação

• Claude Desktop com um clique: construa o pacote .dxt a partir de dxt/manifest.json (veja dxt/README.md).
• Docker: docker build -t n8n-mcp . && docker run --rm -i -e N8N_API_URL=... -e N8N_API_KEY=... n8n-mcp.
• Render: coloque render.yaml e clique em "Novo a partir do Blueprint".
• Railway: railway.toml — railway up na raiz do repositório.
• Fly.io: fly.toml — fly launch --copy-config.

Instalação

Requer Node 20 ou posterior.

Como ferramenta CLI

npm install -g @automatelab/n8n-mcp

Como GitHub Action

Use a GitHub Action n8n MCP para fazer lint de fluxos de trabalho, diagnosticar execuções e gerar JSON de fluxo de trabalho no seu pipeline de CI/CD:

- uses: ratamaha-git/n8n-mcp@v1
  with:
    command: 'lint'
    workflow-json: ${{ env.WORKFLOW_JSON }}

Veja ACTION.md e GITHUB-ACTION-SETUP.md para exemplos e detalhes de publicação.

Configure seu host MCP

Cursor (~/.cursor/mcp.json) ou Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "n8n_..."
      }
    }
  }
}

O bloco env é opcional - as 4 ferramentas sem estado funcionam sem ele. Obtenha uma chave de API do n8n: Configurações → API → Criar chave de API.

Reinicie seu host MCP. As 12 ferramentas com notação de ponto (workflow.*, node.*, execution.*) aparecem no painel MCP.

Exemplos de ferramentas

workflow_generate

Use workflow_generate para construir: webhook Stripe → mensagem no Slack + nova linha no Google Sheets.

Retorna JSON de fluxo de trabalho pronto para o diálogo "Importar de arquivo" do n8n.

execution_explain

Aqui está uma execução com falha do n8n. Por que o nó Slack não está disparando? [cole o JSON]

Retorna:

WARNING [Filter] Returned 0 items. Downstream nodes will not execute.
  hint: Common causes: (1) IF/Switch routed to the other branch — check `parameters.conditions`. (2) Filter/Set node dropped everything — inspect its output explicitly.

INFO [Last node executed was "Filter". If the workflow stopped here unexpectedly, check its output items below.]

workflow_lint

Faça lint deste JSON de fluxo de trabalho. [cole o JSON]

Retorna:

ERROR [AI Agent] AI Agent has no `ai_languageModel` sub-node connected. Attach a chat model (e.g. lmChatOpenAi).
WARNING [Webhook] Webhook node has no `webhookId`. n8n auto-generates one on import, so the production URL will change.
WARNING [LegacyFunction] Node type "n8n-nodes-base.function" is deprecated. Use "n8n-nodes-base.code".

Ou no issues found.

Exemplos

O diretório examples/ acompanha dois fluxos de trabalho prontos para importar:

• workflow-stripe-to-slack.json - webhook Stripe distribui para Slack e Google Sheets.
• workflow-rss-to-discord.json - gatilho de feed RSS publica novos itens em um canal do Discord.

Importe qualquer um via diálogo Importar de arquivo do n8n.

Desenvolvimento

git clone https://github.com/ratamaha-git/n8n-mcp
cd n8n-mcp
npm install
npm run build
npm run smoke

npm run smoke inicia o servidor com uma flag --smoke que lista as ferramentas registradas e sai sem vincular stdio. Útil para CI ou verificações de sanidade na primeira execução.

Licença

MIT. Veja LICENSE.

---

Desenvolvido por AutomateLab.