Servidor MCP n8n

Um servidor de Model Context Protocol (MCP) abrangente que fornece aos assistentes de IA acesso direto à sua plataforma de automação n8n. Este servidor permite integração perfeita entre ferramentas de IA (como Claude Desktop) e fluxos de trabalho, variáveis, credenciais e execuções do n8n.

🚀 Recursos

Integração completa com n8n (18 ferramentas)

Gerenciamento de fluxos de trabalho (7 ferramentas)
- list_workflows - Listar todos os fluxos de trabalho
- get_workflow - Obter detalhes do fluxo de trabalho por ID
- create_workflow - Criar novos fluxos de trabalho
- update_workflow - Atualizar fluxos de trabalho existentes
- delete_workflow - Excluir fluxos de trabalho
- activate_workflow - Ativar fluxos de trabalho
- deactivate_workflow - Desativar fluxos de trabalho
Gerenciamento de variáveis (5 ferramentas)
- list_variables - Listar todas as variáveis
- get_variable - Obter variável por chave
- create_variable - Criar novas variáveis
- update_variable - Atualizar variáveis existentes
- delete_variable - Excluir variáveis
Gerenciamento de credenciais (3 ferramentas)
- list_credentials - Listar todas as credenciais (saneadas)
- create_credential - Criar novas credenciais
- delete_credential - Excluir credenciais
Gerenciamento de execuções (2 ferramentas)
- list_executions - Listar execuções de fluxos de trabalho
- get_execution - Obter detalhes da execução por ID
Gerenciamento do sistema (1 ferramenta)
- self_test - Testar conectividade e permissões do servidor

Arquitetura híbrida

Protocolo MCP: Conformidade total com JSON-RPC 2.0 via transporte stdio
Ponte HTTP: Verificações de integridade e endpoints de teste
Detecção automática: Alterna automaticamente entre modos

📦 Instalação

Pré-requisitos

Node.js 18+
Instância do n8n em execução e acessível
Chave de API do n8n configurada

Configuração

Clone o repositório
```
git clone <repository-url>
cd n8n-mcp
```
Instale as dependências
```
npm install
```

Configure o ambiente

cp .env.example .env
# Edit .env with your settings:
# N8N_API_KEY=your-api-key-here
# N8N_BASE_URL=http://localhost:5678
# MCP_PORT=3001

Teste a instalação

# Test HTTP endpoints
node index.js &
curl http://localhost:3001/health

# Test MCP protocol
node test-all-tools.js

🔧 Uso

Para clientes MCP (Claude Desktop, etc.)

O servidor executa como um servidor MCP baseado em stdio para clientes de IA:

node index.js

Configuração do Claude Desktop (~/.claude_desktop_config.json):

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/path/to/n8n-mcp",
      "env": {
        "N8N_API_KEY": "your-n8n-api-key-here",
        "N8N_BASE_URL": "http://localhost:5678"
      }
    }
  }
}

Para monitoramento HTTP

Quando executado em um terminal (TTY), o servidor fornece endpoints HTTP:

node index.js
# Server starts on http://localhost:3001

# Available endpoints:
# GET  /health - Health check
# POST /test   - Run self-test
# GET  /       - Usage instructions

Teste direto do MCP

Teste o protocolo MCP diretamente:

# Initialize connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"self_test","arguments":{}}}' | node index.js

🧪 Testes

Suíte de testes abrangente

Execute a suíte de testes completa para validar todas as 18 ferramentas:

node test-all-tools.js

Isso irá:

Testar a conformidade com o protocolo MCP
Validar todas as definições de ferramentas
Verificar a conectividade com a API do n8n
Verificar o tratamento de erros
Fornecer resultados detalhados

Testes manuais

# Health check
curl http://localhost:3001/health

# Quick self-test
curl -POST http://localhost:3001/test

# Individual tool test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workflows","arguments":{"limit":5}}}' | node index.js

🔒 Segurança

Gerenciamento de chaves de API

Armazene chaves de API em variáveis de ambiente
Use arquivos .env para desenvolvimento local
Nunca envie chaves de API para o controle de versão

Saneamento de credenciais

Os dados de credenciais são automaticamente saneados nas respostas
Apenas metadados (ID, nome, tipo) são expostos
Dados sensíveis de credenciais nunca são retornados

Segurança de rede

O servidor HTTP vincula-se a localhost por padrão
Cabeçalhos CORS configurados para solicitações entre origens
Nenhum dado sensível exposto via endpoints HTTP

🐛 Solução de problemas

Problemas comuns

1. "N8N_API_TOKEN não configurado"

# Solution: Set your API key
export N8N_API_KEY=your-api-key-here
# Or add to .env file

2. Erros de "Conexão recusada"

# Solution: Check n8n is running
curl http://localhost:5678/api/v1/workflows?limit=1 -H "X-N8N-API-KEY: your-key"

3. "A licença não permite o recurso: variáveis"

# This is expected for n8n Community Edition
# Variables require n8n Pro/Enterprise license
# The tool will still work but return license errors

4. "Método GET não permitido" para credenciais

# Some n8n configurations restrict credential access
# Check your n8n security settings

5. Porta já em uso (EADDRINUSE)

# Solution: Kill existing process or change port
pkill -f "node index.js"
# Or set different port: MCP_PORT=3002 node index.js

Modo de depuração

Ative o registro detalhado:

DEBUG=1 node index.js

Validar configuração

# Test n8n connectivity
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows?limit=1

# Test MCP server
node test-all-tools.js

📊 Monitoramento

Verificações de integridade

# Basic health
curl http://localhost:3001/health

# Detailed system test
curl -X POST http://localhost:3001/test | jq '.result.summary'

Monitoramento de desempenho

O servidor registra todas as execuções de ferramentas e fornece informações de tempo:

Tempo de execução da ferramenta
Tempo de resposta da API do n8n
Taxas e tipos de erros

🤝 Contribuição

Configuração de desenvolvimento

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações
Execute os testes: node test-all-tools.js
Envie uma solicitação de pull

Adicionando novas ferramentas

Adicione a definição da ferramenta em setupToolHandlers()
Implemente o método da ferramenta
Adicione o caso de teste em test-all-tools.js
Atualize a documentação

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🔗 Projetos relacionados

n8n - Plataforma de automação de fluxos de trabalho
Model Context Protocol - Especificação do protocolo
Claude Desktop - Assistente de IA com suporte a MCP

📞 Suporte

Problemas: Use o GitHub Issues para relatórios de bugs
Discussões: Use o GitHub Discussions para perguntas
Documentação: Consulte este README e comentários no código

Pronto para automatizar com IA? 🤖✨

Seus fluxos de trabalho do n8n agora estão acessíveis aos assistentes de IA através do Model Context Protocol!

n8n

Documentação