mcp-n8n

MCP (Model Context Protocol) server para N8N focado em CONSTRUÇÃO DE WORKFLOWS pela Samara. 18 tools em 5 categorias, rodando via stdio.

Diferencial: Paule descreve em linguagem natural o que quer ("Samara, monta um workflow que recebe WhatsApp, classifica com IA, e responde") e a Samara monta o workflow no N8N automaticamente — usando 1 dos 3 modos inteligentes (template / scaffold / LLM).

Tools (18)

1. CRUD (5) — manipular workflows existentes

• list_workflows — lista workflows do N8N

• get_workflow — pega JSON completo por id

• create_workflow — cria novo workflow

• update_workflow — atualiza workflow existente

• delete_workflow — ⚠ destrutivo, pede confirmação

2. Execução (3)

• execute_workflow — dispara workflow (com payload opcional)

• get_execution — status + dados de uma execution

• list_executions — histórico de execuções

3. Import / Export + Templates (2)

• import_workflow — importa JSON local pro N8N

• export_workflow — exporta workflow do N8N pra JSON

4. Sync local (2)

• sync_from_templates — importa todos os JSONs de N8N_TEMPLATES_DIR pro N8N

• sync_to_templates — exporta todos os workflows do N8N pra N8N_TEMPLATES_DIR

5. CONSTRUÇÃO (6) — o coração do "Samara monta fluxos"

• build_workflow_from_spec — a principal: spec em linguagem natural → workflow JSON

• list_node_types — descobre nodes disponíveis no N8N

• get_node_schema — schema detalhado de 1 node

• validate_workflow — valida JSON antes de criar (pega nodes inválidos, ciclos, connections quebradas)

• export_workflow_diagram — gera diagrama Mermaid

• workflow_versions — versionamento git-like (list, save, restore, diff)

Os 3 modos de construção

build_workflow_from_spec é inteligente — escolhe o melhor modo baseado na spec:

Paule pode forçar modo com mode: "template" | "scaffold" | "llm". Default: auto (Samara escolhe).

Exemplo de uso

Paule: "Samara, monta um workflow que recebe POST no webhook, valida JWT, salva no Supabase e responde 200"

Samara:

1. Detecta keywords: webhook, valida, salva, responde → modo scaffold (lista nodes)

2. Invoca mcp__n8n__build_workflow_from_spec com a spec

3. Samara no Claude Code refina o JSON retornado (adiciona nodes de validação JWT, ajusta Supabase, etc)

4. Invoca mcp__n8n__validate_workflow pra confirmar

5. Invoca mcp__n8n__export_workflow_diagram pra Paule ver visual

6. Paule aprova → invoca mcp__n8n__create_workflow

7. Retorna URL do webhook + ID

Instalação

1. Pré-requisitos

• Node.js 22.6+ (com --experimental-strip-types)

• N8N rodando em algum lugar (cloud ou self-hosted) com API habilitada

• API key do N8N (Settings → API)

2. Instalar

cd "C:\Users\paule\Documents\PROGRAMAÇÃO\mcp-n8n"
npm install

3. Configurar .env

Copy-Item .env.example .env
notepad .env

Preencha:

• N8N_API_KEY — key criada no N8N UI (Settings → API → Create API Key)

• N8N_BASE_URL — http://localhost:5678/api/v1 pra self-hosted, ou https://api.n8n.cloud/api/v1 pra cloud

• N8N_TEMPLATES_DIR — opcional, default já aponta pra C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES

4. Registrar no Claude Code

Edite C:\Users\paule\.claude.json e adicione na seção mcpServers:

{
  "mcpServers": {
    "n8n": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "--no-warnings",
        "C:\\Users\\paule\\Documents\\PROGRAMAÇÃO\\mcp-n8n\\src\\server.ts"
      ],
      "env": {
        "N8N_API_KEY": "sua-key-aqui",
        "N8N_BASE_URL": "http://localhost:5678/api/v1",
        "N8N_TEMPLATES_DIR": "C:\\Users\\paule\\Documents\\PROGRAMAÇÃO\\N8N\\TEMPLETES"
      }
    }
  }
}

Reinicie o Claude Code. Tools aparecem como mcp__n8n__<tool_name>.

Como a Samara usa

Samara detecta pedidos relacionados a N8N e invoca o MCP automaticamente. Exemplos em linguagem natural:

Construção

• "Samara, monta um workflow que recebe WhatsApp e classifica com IA" → build_workflow_from_spec (modo llm)

• "Samara, faz um workflow parecido com o de WhatsApp que tenho em TEMPLATES" → build_workflow_from_spec (modo template)

• "Samara, cria workflow Webhook → IF → HTTP Request → Responder" → build_workflow_from_spec (modo scaffold)

Discovery e validação

• "Samara, quais nodes N8N eu tenho disponível?" → list_node_types

• "Samara, me mostra o schema do OpenAI node" → get_node_schema

• "Samara, valida esse workflow antes de criar" → validate_workflow

Visualização

• "Samara, gera o diagrama Mermaid desse workflow" → export_workflow_diagram

• "Samara, me mostra o fluxo visual antes de criar" → build_workflow_from_spec + export_workflow_diagram

Versionamento

• "Samara, salva versão desse workflow" → workflow_versions(action="save")

• "Samara, lista versões" → workflow_versions(action="list")

• "Samara, restaura versão 2026-07-01" → workflow_versions(action="restore")

CRUD tradicional

• "Samara, lista workflows" → list_workflows

• "Samara, executa workflow abc" → execute_workflow

• "Samara, deleta workflow xyz" → ⚠ pede confirmação inline → delete_workflow

Política de confirmação (honra 06/07/2026)

• Criações automáticas (sem perguntar): create_workflow, build_workflow_from_spec, import_workflow, sync_from_templates, validate_workflow, export_workflow_diagram, workflow_versions save

• Execução (execute_workflow): automática se workflow já foi usado antes; pede confirmação se for primeira vez

• Destruição (delete_workflow, update_workflow): SEMPRE pede confirmação inline

• Leitura (list_*, get_*): automática, sem side effects

Samara aplica essa política antes de invocar a tool.

Arquitetura

Claude Code (Paule)
   │
   │  mcp__n8n__<tool_name>
   ▼
mcp-n8n v0.2 (stdio, Node 22 + TypeScript strip-types, 18 tools)
   │
   │  fetch + X-N8N-API-KEY
   ▼
N8N REST API (cloud ou self-hosted)
   │
   ├── /workflows
   ├── /executions
   ├── /node-types
   └── /workflows/{id}/execute

Local:
- C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES\         (25+ templates salvos)
- C:\Users\paule\Documents\PROGRAMAÇÃO\N8N\TEMPLETES\.versions\ (git-like backup)

Teste rápido

Com o server registrado e N8N rodando:

1. Abra nova conversa com Claude Code

2. Diga: "Samara, monta um workflow que recebe webhook POST, valida, e responde 200"

3. Samara invoca mcp__n8n__build_workflow_from_spec

4. Você vê o JSON gerado + diagrama Mermaid

5. Se aprovar, Samara invoca mcp__n8n__create_workflow

6. Retorna ID do workflow + URL do webhook

Se aparecer erro 401: API key não configurada. Defina no .claude.json.

Troubleshooting

"Tool not found: mcp__n8n__list_workflows"

• Claude Code não detectou o MCP. Reinicie.

• Verifique path absoluto em mcp.json.

"N8N_API_KEY não configurada"

• Defina no .claude.json em mcpServers.n8n.env.N8N_API_KEY.

• Ou crie .env no projeto mcp-n8n.

"fetch failed: ECONNREFUSED"

• N8N não está rodando. Inicie: npx n8n ou docker run -p 5678:5678 n8nio/n8n.

• Verifique N8N_BASE_URL (default 5678).

build_workflow_from_spec retorna scaffold estranha

• Samara refina antes de criar. Use validate_workflow + export_workflow_diagram pra revisar.

• Force modo específico: mode: "scaffold" se spec lista nodes, ou mode: "template" se tem base.

Versão restaurada não funciona

• Versões ficam em N8N_VERSIONS_DIR/.versions/. Verifique que o arquivo existe.

• Use workflow_versions(action="list") pra ver todas.

Roadmap (Fase futura)

• Cache local de workflows (evita chamada API repetida)

• Validação de schema de workflow mais rigorosa (TS validation)

• Webhook server embutido pra receber notificações de execução concluída

• CLI wrapper (npx mcp-n8n list) pra uso fora do MCP

• Diff visual (além de node count)

• Templates como recipes com metadados (tags, descrição, autor)

Inspirado em

• mcp-meta-ads do Paule (MCP similar pra Meta Ads)

• @modelcontextprotocol/sdk oficial

• N8N REST API: https://docs.n8n.io/api/

mcp-n8n v0.2 — criado 07/07/2026. Samara agora não só gerencia N8N, ela CONSTRÓI workflows.