mcp-n8n

Opere e construa n8n: 55 ferramentas com validação, edições cirúrgicas, teste de webhook e rollback.

Documentação

Servidor MCP n8n

Opere e construa n8n a partir do Cursor ou Claude — administração da sua instância (usuários, projetos, execuções, auditoria) e um ciclo completo de construção: um catálogo de 560 nós com esquemas reais de parâmetros extraídos dos pacotes oficiais do n8n, validação antes de salvar, reparo automático, snapshots com rollback e diff, depuração por nó, relatórios de saúde e backup completo da instância.

Duas variáveis de ambiente. Roda na sua máquina (stdio) ou como servidor HTTP remoto. Sem conta hospedada.

🎯 Otimização de Tokens

Este servidor é otimizado para minimizar o consumo de tokens, resolvendo um dos maiores problemas dos servidores MCP - o uso excessivo de tokens de API.

O que otimizamos:

Redução de 90% nos tokens para listagem de workflows com o novo endpoint n8n_list_workflows_summary
Filtragem de campos - solicite apenas os dados que você precisa
Padrões inteligentes - reduzido de 100 para 10-20 resultados por consulta
Avisos inteligentes - alertas quando operações consumirem muitos tokens

Consulte TOKEN_OPTIMIZATION.md para o guia detalhado de uso.

✨ Recursos

🔄 Gerenciamento de Workflows

Criar e Implantar: Construa workflows com descrições em linguagem natural
Operações CRUD: Gerenciamento completo do ciclo de vida (Criar, Ler, Atualizar, Excluir)
Controle de Ativação: Habilite/desabilite workflows sob demanda
Transferência de Projetos: Mova workflows entre projetos sem interrupções
Gerenciamento de Tags: Organize workflows com tags personalizadas

📊 Monitoramento de Execuções

Acompanhamento em Tempo Real: Monitore execuções de workflows com filtros avançados
Insights Detalhados: Acesse dados completos de execução e logs
Recuperação de Erros: Repita execuções com falha automaticamente
Ferramentas de Limpeza: Gerencie o histórico de execuções com eficiência

🔐 Gerenciamento de Credenciais

Criação Segura: Adicione credenciais para qualquer serviço
Descoberta de Esquemas: Descubra automaticamente os campos obrigatórios para tipos de credenciais
Isolamento de Projetos: Transfira credenciais entre projetos com segurança
Suporte a Tipos: Compatível com todos os tipos de credenciais do n8n

🧱 Construtor de Workflows

Catálogo completo de nós — 560 nós com esquemas reais: extraídos diretamente de n8n-nodes-base e @n8n/n8n-nodes-langchain (parâmetros com tipos, opções permitidas, condições de exibição, credenciais, typeVersion mais recente), regenerados semanalmente por CI. Pesquise com n8n_search_nodes, inspecione com n8n_get_node
Validação real: n8n_validate_workflow verifica contra os esquemas reais — tipos de nós inexistentes, parâmetros obrigatórios ausentes (incluindo condicionalmente obrigatórios), valores de opções inválidos, typeVersion incorreto, conexões quebradas — antes de salvar/ativar
Verificação de expressões: detecta expressões {{ }} sem o prefixo = e referências a nós que não existem no workflow
Reparo automático: n8n_autofix_workflow corrige typeVersion/posições ausentes, nomes duplicados, conexões pendentes e prefixos de expressões — visualize antes, aplique com um snapshot
Edições cirúrgicas: n8n_update_workflow_partial adiciona/remove nós e conexões sem reescrever todo o fluxo
Modelos públicos: pesquise e importe de n8n.io (n8n_search_public_templates, n8n_import_public_template) além de 100 modelos incluídos como alternativa
Prompts guiados: prompts MCP build-workflow e fix-workflow conduzem qualquer agente pelo ciclo completo de construir/validar/testar/reparar

🔬 Depuração Profunda e Saúde

Dados de execução por nó: n8n_get_node_execution_data mostra exatamente quais dados passaram por um nó (status, contagens de itens, amostras de saída, detalhes de erro) sem baixar toda a execução
Ciclo de depuração: n8n_debug_last_error retorna o nó com falha e a mensagem do último erro
Relatórios de saúde: n8n_workflow_health calcula taxa de sucesso, contagem de falhas, duração média e última falha por workflow a partir de execuções recentes, ordenados do pior para o melhor

🛡️ Rede de Segurança e Testes Reais

Snapshots automáticos: antes de cada atualização, edição parcial, correção automática ou exclusão, o estado anterior é salvo localmente (~/.mcp-n8n/snapshots, configurável com N8N_SNAPSHOT_DIR)
Rollback: n8n_rollback_workflow restaura qualquer snapshot — até recria um workflow excluído (recreate=true)
Diff: n8n_diff_workflow_snapshot compara um snapshot com o estado atual (nós adicionados/removidos/modificados, parâmetros alterados, mudanças de conexão) antes de decidir reverter
Backup completo da instância: n8n_export_all_workflows salva cada workflow como arquivos JSON; n8n_import_workflows os restaura
Testes de ponta a ponta: n8n_trigger_webhook chama um workflow com gatilho Webhook na instância e retorna a resposta HTTP real, para que o agente possa verificar se o fluxo realmente funciona

🎯 Modelos Incluídos

100 pontos de partida locais com correspondência por palavras-chave, se você preferir não acessar n8n.io

🏗️ Organização e Administração

Tags: Categorize e organize recursos
Variáveis: Gerenciamento centralizado de variáveis de ambiente
Projetos: Suporte a projetos multi-tenant
Usuários e Permissões: Gerenciamento completo de controle de acesso
Logs de Auditoria: Gere relatórios de segurança e conformidade

🚀 Início Rápido

Instalação via npm (Recomendado)

Esta é a maneira mais fácil de começar:

npm install -g mcp-n8n

Configuração

Obtenha suas credenciais da API do n8n:
- Navegue até sua instância do n8n → Configurações → API do n8n
- Gere uma nova chave de API
Configure o Claude Desktop:

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

Opção A - Usando instalação global (se você executou npm install -g mcp-n8n):

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS é opcional (all por padrão). Use core,builder se quiser operações + criação sem ferramentas de administração de usuários/projetos. Use admin apenas para administração da instância.

Modo HTTP remoto (opcional)

Por padrão, o servidor se comunica via stdio (local). Para executá-lo como um servidor remoto compartilhado (ex.: em Docker ou em um VPS), defina uma porta:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

Isso expõe o protocolo MCP via HTTP streamable na porta 3000 além de um endpoint GET /health. N8N_MCP_HTTP_TOKEN é fortemente recomendado: quando definido, cada requisição deve incluir Authorization: Bearer <token>. Aponte qualquer cliente MCP que suporte HTTP streamable para http://your-host:3000 com esse cabeçalho.

Opção B - Usando npx (sem instalação necessária, sempre versão mais recente):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configure o Cursor:

Adicione nas configurações MCP do Cursor (Configurações → Extensões → MCP):

Recomendado - Usando npx (sempre usa a versão mais recente):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Nota: O Cursor exige o uso de npx para servidores MCP. A flag -y instala/atualiza automaticamente o pacote sem solicitar confirmação.

Opção C - Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

O volume /data persiste os snapshots dos workflows entre execuções.

Reinicie o Claude Desktop ou o Cursor

💬 Exemplos de Uso

Uma vez configurado, interaja com o n8n usando linguagem natural:

Criando Workflows

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

Usando Modelos

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

Gerenciando Workflows

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

Monitoramento e Depuração

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

🛠️ Ferramentas Disponíveis

Workflows

n8n_create_workflow - Crie novos workflows (valida primeiro)
n8n_list_workflows_summary - Listagem eficiente em tokens
n8n_list_workflows - Detalhes completos com filtragem opcional de campos
n8n_get_workflow - JSON completo do workflow
n8n_update_workflow - Substitua campos (campos omitidos mantêm valores atuais)
n8n_update_workflow_partial - Edições cirúrgicas: adicione/remova nós e conexões
n8n_delete_workflow - Remova workflows permanentemente
n8n_activate_workflow / n8n_deactivate_workflow
n8n_transfer_workflow / ferramentas de tags

Segurança e Testes

n8n_list_workflow_snapshots - Histórico local de cada alteração feita através deste servidor
n8n_rollback_workflow - Restaure uma versão anterior, ou recrie um workflow excluído
n8n_diff_workflow_snapshot - Compare um snapshot com o estado atual antes de reverter
n8n_trigger_webhook - Chame um workflow webhook e obtenha a resposta real
n8n_export_all_workflows / n8n_import_workflows - Backup e restauração completos da instância

Construtor

n8n_search_nodes / n8n_get_node - Catálogo completo: 560 nós com esquemas reais de parâmetros
n8n_validate_workflow - Verifique JSON contra esquemas reais antes de salvar/ativar
n8n_autofix_workflow - Reparos mecânicos: typeVersion, posições, duplicatas, conexões pendentes, prefixos de expressões
n8n_search_public_templates / n8n_import_public_template - Biblioteca oficial do n8n.io
n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - Modelos incluídos

100 Modelos Incluídos em 13 categorias:

E-commerce: automação Shopify, agentes de suporte WooCommerce
Redes Sociais: automação Instagram, TikTok, LinkedIn, Twitter
IA/Chat: Chatbots, agentes de IA, assistentes de voz
Comunicação: automação WhatsApp, Telegram, Email
Conteúdo: automação de blogs, geração de vídeos, otimização SEO
RH/Recrutamento: triagem de currículos, busca de candidatos
Vendas/CRM: geração de leads, pipelines de prospecção
Finanças: análise de ações, extração de faturas
Raspagem de Dados: Google Maps, LinkedIn, Amazon, TikTok
Monitoramento: uptime de sites, rastreamento de concorrentes
Produtividade: calendário, Notion, automação de agendamentos

Execuções (4 ferramentas)

n8n_list_executions - Filtre por status, workflow, projeto
n8n_get_execution - Dados detalhados de execução
n8n_delete_execution - Remova registros de execução
n8n_retry_execution - Repita execuções com falha
n8n_debug_last_error - Nó com falha + mensagem do último erro
n8n_get_node_execution_data - Dados que passaram por um nó específico
n8n_workflow_health - Taxa de sucesso, falhas e duração por workflow

Credenciais (4 ferramentas)

n8n_create_credential - Adicione novas credenciais
n8n_delete_credential - Remova credenciais (apenas proprietário)
n8n_get_credential_schema - Descubra campos obrigatórios
n8n_transfer_credential - Mova entre projetos

Organização (19 ferramentas)

Tags: Criar, listar, obter, atualizar, excluir Variáveis: Criar, listar, atualizar, excluir Usuários: Listar, criar, obter, excluir, alterar função Projetos: Criar, listar, atualizar, excluir, gerenciar usuários

Avançado (2 ferramentas)

n8n_generate_audit - Relatórios de auditoria de segurança
n8n_pull_source_control - Integração com controle de versão

61 ferramentas por padrão (N8N_TOOLSETS=all). core,builder expõe 28. Além de 2 prompts MCP (build-workflow, fix-workflow).

📚 Documentação

Guia de Início Rápido - Comece a usar em 5 minutos
Exemplos e Casos de Uso - Exemplos reais de automação
Referência de Nós - Documentação detalhada das ferramentas
Changelog - Histórico de versões e atualizações

🏗️ Estrutura do Projeto

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 Desenvolvimento

Instalação Local (Para Desenvolvimento)

Se você quiser contribuir ou testar alterações locais:

1. Configuração

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. Configure com Build Local

Para Claude Desktop, adicione em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Para Cursor, adicione nas configurações MCP:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Importante: Substitua /absolute/path/to/mcp-n8n/ pelo caminho absoluto real do seu repositório clonado (ex.: /Users/yourname/projects/mcp-n8n/).

3. Testes

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

Como Executar

Para executar o script principal, execute:

python main.py

Como Testar

Para executar os testes, execute:

pytest test_main.py

📋 Requisitos

Node.js: 20 ou superior
Instância n8n: Self-hosted ou n8n Cloud (plano pago)
Chave de API do n8n: Necessária para autenticação
IDE com IA: Claude Desktop ou Cursor com suporte a MCP

Requisitos do n8n

Self-hosted: Acesso completo à API ✅
n8n Cloud: Requer plano pago para acesso à API
Versão: Compatível com n8n v1.0.0+

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de funcionalidade (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
Envie para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📝 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

n8n - A plataforma de automação de fluxos de trabalho
Anthropic - Claude e Model Context Protocol
Cursor - Editor de código com IA

🔗 Recursos

⚠️ Notas Importantes

Acesso à API

O n8n Cloud requer um plano pago para acessar a API
O n8n self-hosted tem acesso completo à API em todos os planos
Algumas operações exigem permissões de proprietário/admin

Segurança

Nunca faça commit de arquivos .env com credenciais
Use variáveis de ambiente para dados sensíveis
Chaves de API concedem acesso total à sua instância n8n
Rotacione as chaves de API regularmente por segurança

Limite de Taxa

Respeite os limites de taxa da API do n8n
Use paginação para grandes conjuntos de resultados
Implemente tratamento de erros para respostas de limite de taxa

🐛 Solução de Problemas

Problemas de Conexão

Problema: "Não é possível conectar à API do n8n"

Verifique se N8N_BASE_URL está correto e acessível
Confirme se a chave de API é válida
Garanta que a instância n8n esteja em execução

Erros de Permissão

Problema: "Permissões insuficientes"

Algumas operações exigem o papel de proprietário/admin
Verifique se seu usuário tem as permissões adequadas
Confira os direitos de acesso no nível do projeto

Problemas com Modelos

Problema: "Modelo não encontrado"

Garanta que o diretório examples/ esteja presente
Verifique se templates-metadata.json existe
Confira se as referências aos arquivos de modelo estão corretas

💡 Dicas e Boas Práticas

Comece com Modelos: Use modelos pré-construídos como ponto de partida
Use Tags: Organize fluxos de trabalho com tags para facilitar o gerenciamento
Monitore Execuções: Verifique regularmente execuções com falha
Limpeza: Remova dados antigos de execução para economizar espaço
Controle de Versão: Use os recursos integrados de controle de versão do n8n
Teste Primeiro: Teste os fluxos de trabalho antes de ativá-los em produção

📧 Suporte

Problemas: GitHub Issues
Discussões: GitHub Discussions
Comunidade n8n: community.n8n.io

⬆ Voltar ao Topo