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:

Modo	Quando	Como funciona
template	Spec menciona keyword que casa com template salvo	Carrega template de N8N_TEMPLATES_DIR/, adapta nome, devolve JSON
scaffold	Spec lista nodes separados por →, -> ou vírgulas	Monta workflow linear com esses nodes conectados
llm	Spec vaga em linguagem natural	Detecta palavras-chave (webhook/cron/ia/http/if) e gera scaffold heurístico

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.