n8n MCP

Servidor MCP n8n que fornece a assistentes de IA acesso à documentação de nós, propriedades, operações e contexto de automação de workflows do n8n.

GitHub

22.9k

Experimente este MCPPatrocinado

Documentação

n8n-MCP

Um servidor Model Context Protocol (MCP) que fornece aos assistentes de IA acesso abrangente à documentação, propriedades e operações dos nós do n8n. Implante em minutos para dar ao Claude e outros assistentes de IA conhecimento profundo sobre os 2.755 nós de automação de fluxo de trabalho do n8n (832 principais + 1.923 da comunidade).

Visão Geral

O n8n-MCP atua como uma ponte entre a plataforma de automação de fluxo de trabalho do n8n e os modelos de IA, permitindo que eles entendam e trabalhem com os nós do n8n de forma eficaz. Ele fornece acesso estruturado a:

2.755 nós do n8n - 832 nós principais + 1.923 nós da comunidade (1.591 verificados)
Propriedades dos nós - 99% de cobertura com esquemas detalhados
Operações dos nós - 66,5% de cobertura das ações disponíveis
Documentação - 86% de cobertura da documentação oficial do n8n (incluindo nós de IA)
Ferramentas de IA - 267 variantes de ferramentas com capacidade de IA detectadas com documentação completa
Exemplos do mundo real - 156 configurações classificadas extraídas de modelos populares
Biblioteca de modelos - 2.352 modelos de fluxo de trabalho com 99,96% de cobertura de metadados de IA
Nós da comunidade - Pesquise integrações verificadas da comunidade com filtro source

Apoie Este Projeto

n8n-mcp começou como uma ferramenta pessoal, mas agora ajuda dezenas de milhares de desenvolvedores a automatizar seus fluxos de trabalho de forma eficiente. Manter e desenvolver este projeto compete com meu trabalho remunerado. Seu patrocínio me ajuda a dedicar tempo focado a novos recursos, responder rapidamente a problemas, manter a documentação atualizada e garantir compatibilidade com as versões mais recentes do n8n. Torne-se um patrocinador

💼 Precisa que seja construído para você? Trabalhe com AiAdvisors — auditorias, construções e operações de automação n8n, administrado pelo autor do n8n-mcp e n8n-skills.

Aviso Importante de Segurança

NUNCA edite seus fluxos de trabalho de produção diretamente com IA! Sempre:

Faça uma cópia do seu fluxo de trabalho antes de usar ferramentas de IA
Teste no ambiente de desenvolvimento primeiro
Exporte backups de fluxos de trabalho importantes
Valide as alterações antes de implantar em produção

Os resultados da IA podem ser imprevisíveis. Proteja seu trabalho!

Início Rápido

A maneira mais rápida de experimentar o n8n-MCP - sem instalação, sem configuração:

dashboard.n8n-mcp.com

Nível gratuito: 100 chamadas de ferramentas/dia
Acesso instantâneo: Comece a construir fluxos de trabalho imediatamente
Sempre atualizado: Últimos nós e modelos do n8n
Sem infraestrutura: Nós cuidamos de tudo

Basta se inscrever, obter sua chave de API e conectar seu cliente MCP.

Quer auto-hospedar? Consulte o Guia de Auto-Hospedagem para opções de instalação com npx, Docker, Railway e local.

Integração com n8n

Quer usar o n8n-MCP com sua instância do n8n? Confira nosso abrangente Guia de Implantação no n8n para:

Testes locais com o nó MCP Client Tool
Implantação em produção com Docker Compose
Implantação em nuvem na Hetzner, AWS e outros provedores
Solução de problemas e práticas recomendadas de segurança

Autenticação Cloudflare Access

Se sua instância do n8n estiver atrás do Cloudflare Access (Zero Trust), forneça seu token de serviço para que o n8n-MCP possa autenticar:

N8N_CF_CLIENT_ID - Cloudflare Access Client ID
N8N_CF_CLIENT_SECRET - Cloudflare Access Client Secret

Quando definidos, eles são enviados como cabeçalhos CF-Access-Client-Id / CF-Access-Client-Secret nas solicitações de API do n8n, sondagens de versão/saúde e execuções de webhook. O token é confinado à origem N8N_API_URL — chamadas de webhook para um host diferente (por exemplo, uma origem WEBHOOK_URL dividida) não o recebem, para evitar vazamento do token.

Agentes n8n e MCP em Nível de Instância (Opcional)

Para usar n8n_manage_agents, n8n_explore_node_resources e o fallback do projeto em n8n_list_catalog, defina:

N8N_MCP_ACCESS_TOKEN - Chave de API MCP das Configurações do n8n → MCP em nível de instância → defina o status do MCP como Ativado. Este é um segredo separado de N8N_API_KEY e deve ser armazenado da mesma forma. O endpoint MCP é derivado de N8N_API_URL; instâncias que servem MCP de um host dividido (N8N_MCP_BASE_URL) não são suportadas.

Consulte Conectando o n8n-mcp ao servidor MCP em nível de instância do n8n para o passo a passo completo da configuração, incluindo como obter o token na interface do n8n, pré-requisitos e solução de problemas.

Conecte sua IDE

O n8n-MCP funciona com várias IDEs e ferramentas com tecnologia de IA:

Claude Code - Configuração rápida para Claude Code CLI
Visual Studio Code - VS Code com integração GitHub Copilot
Cursor - Configuração passo a passo da IDE Cursor
Windsurf - Integração Windsurf com regras de projeto
Codex - Guia de integração Codex
Antigravity - Guia de integração Antigravity

Adicione Habilidades Claude (Opcional)

Potencialize sua construção de fluxos de trabalho n8n com habilidades especializadas que ensinam a IA a construir fluxos de trabalho prontos para produção!

Saiba mais: repositório n8n-skills

Configuração de Projeto Claude

Para obter os melhores resultados ao usar o n8n-MCP com Projetos Claude, use estas instruções de sistema aprimoradas:

You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.

## Core Principles

### 1. Silent Execution
CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.

### 2. Parallel Execution
When operations are independent, execute them in parallel for maximum performance.

### 3. Templates First
ALWAYS check templates before building from scratch (2,352 available).

### 4. Multi-Level Validation
Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.

### 5. Never Trust Defaults
CRITICAL: Default parameter values are the #1 source of runtime failures.
ALWAYS explicitly configure ALL parameters that control node behavior.

## Workflow Process

1. **Start**: Call `tools_documentation()` for best practices

2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
   - `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering
   - `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task
   - `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword')
   - `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type

   **Filtering strategies**:
   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
   - By time: `maxSetupMinutes: 15` for quick wins
   - By service: `requiredService: "openai"` for compatibility

3. **Node Discovery** (if no suitable template - parallel execution)
   - Think deeply about requirements. Ask clarifying questions if unclear.
   - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
   - `search_nodes({query: 'trigger'})` - Browse triggers
   - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes

4. **Configuration Phase** (parallel for multiple nodes)
   - `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default)
   - `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens)
   - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens)
   - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties
   - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation
   - Show workflow architecture to user for approval before proceeding

5. **Validation Phase** (parallel for multiple nodes)
   - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check
   - `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
   - Fix ALL errors before proceeding

6. **Building Phase**
   - If using template: `get_template(templateId, {mode: "full"})`
   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
   - Build from validated configurations
   - EXPLICITLY set ALL parameters - never rely on defaults
   - Connect nodes with proper structure
   - Add error handling
   - Use n8n expressions: $json, $node["NodeName"].json
   - Build in artifact (unless deploying to n8n instance)

7. **Workflow Validation** (before deployment)
   - `validate_workflow(workflow)` - Complete validation
   - `validate_workflow_connections(workflow)` - Structure check
   - `validate_workflow_expressions(workflow)` - Expression validation
   - Fix ALL issues before deployment

8. **Deployment** (if n8n API configured)
   - `n8n_create_workflow(workflow)` - Deploy
   - `n8n_validate_workflow({id})` - Post-deployment check
   - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
   - `n8n_test_workflow({workflowId})` - Test workflow execution

## Critical Warnings

### Never Trust Defaults
Default values cause runtime failures. Example:
```json
// FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

// WORKS - all parameters explicit
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
```

### Example Availability
`includeExamples: true` returns real configurations from workflow templates.
- Coverage varies by node popularity
- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`

## Validation Strategy

### Level 1 - Quick Check (before building)
`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms)

### Level 2 - Comprehensive (before building)
`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes

### Level 3 - Complete (after building)
`validate_workflow(workflow)` - Connections, expressions, AI tools

### Level 4 - Post-Deployment
1. `n8n_validate_workflow({id})` - Validate deployed workflow
2. `n8n_autofix_workflow({id})` - Auto-fix common errors
3. `n8n_executions({action: 'list'})` - Monitor execution status

## Response Format

### Initial Creation
```
[Silent tool execution in parallel]

Created workflow:
- Webhook trigger → Slack notification
- Configured: POST /webhook → #general channel

Validation: All checks passed
```

### Modifications
```
[Silent tool execution]

Updated workflow:
- Added error handling to HTTP node
- Fixed required Slack parameters

Changes validated successfully.
```

## Batch Operations

Use `n8n_update_partial_workflow` with multiple operations in a single call:

GOOD - Batch multiple operations:
```json
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [
    {type: "updateNode", nodeId: "slack-1", changes: {...}},
    {type: "updateNode", nodeId: "http-1", changes: {...}},
    {type: "cleanStaleConnections"}
  ]
})
```

BAD - Separate calls:
```json
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})
```

### CRITICAL: addConnection Syntax

The `addConnection` operation requires **four separate string parameters**. Common mistakes cause misleading errors.

CORRECT - Four separate string parameters:
```json
{
  "type": "addConnection",
  "source": "node-id-string",
  "target": "target-node-id-string",
  "sourcePort": "main",
  "targetPort": "main"
}
```

**Reference**: [GitHub Issue #327](https://github.com/czlonkowski/n8n-mcp/issues/327)

### CRITICAL: IF Node Multi-Output Routing

IF nodes have **two outputs** (TRUE and FALSE). Use the **`branch` parameter** to route to the correct output:

```json
n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
    {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
  ]
})
```

**Note**: Without the `branch` parameter, both connections may end up on the same output, causing logic errors!

### removeConnection Syntax

Use the same four-parameter format:
```json
{
  "type": "removeConnection",
  "source": "source-node-id",
  "target": "target-node-id",
  "sourcePort": "main",
  "targetPort": "main"
}
```

## Important Rules

### Core Behavior
1. **Silent execution** - No commentary between tools
2. **Parallel by default** - Execute independent operations simultaneously
3. **Templates first** - Always check before building (2,352 available)
4. **Multi-level validation** - Quick check → Full validation → Workflow validation
5. **Never trust defaults** - Explicitly configure ALL parameters

### Attribution & Credits
- **MANDATORY TEMPLATE ATTRIBUTION**: Share author name, username, and n8n.io link
- **Template validation** - Always validate before deployment (may need updates)

### Code Node Usage
- **Avoid when possible** - Prefer standard nodes
- **Only when necessary** - Use code node as last resort
- **AI tool capability** - ANY node can be an AI tool (not just marked ones)

### Most Popular n8n Nodes (for get_node):

1. **n8n-nodes-base.code** - JavaScript/Python scripting
2. **n8n-nodes-base.httpRequest** - HTTP API calls
3. **n8n-nodes-base.webhook** - Event-driven triggers
4. **n8n-nodes-base.set** - Data transformation
5. **n8n-nodes-base.if** - Conditional routing
6. **n8n-nodes-base.manualTrigger** - Manual workflow execution
7. **n8n-nodes-base.respondToWebhook** - Webhook responses
8. **n8n-nodes-base.scheduleTrigger** - Time-based triggers
9. **@n8n/n8n-nodes-langchain.agent** - AI agents
10. **n8n-nodes-base.googleSheets** - Spreadsheet integration
11. **n8n-nodes-base.merge** - Data merging
12. **n8n-nodes-base.switch** - Multi-branch routing
13. **n8n-nodes-base.telegram** - Telegram bot integration
14. **@n8n/n8n-nodes-langchain.lmChatOpenAi** - OpenAI chat models
15. **n8n-nodes-base.splitInBatches** - Batch processing
16. **n8n-nodes-base.openAi** - OpenAI legacy node
17. **n8n-nodes-base.gmail** - Email automation
18. **n8n-nodes-base.function** - Custom functions
19. **n8n-nodes-base.stickyNote** - Workflow documentation
20. **n8n-nodes-base.executeWorkflowTrigger** - Sub-workflow calls

**Note:** LangChain nodes use the `@n8n/n8n-nodes-langchain.` prefix, core nodes use `n8n-nodes-base.`

Salve estas instruções em seu Projeto Claude para obter assistência ideal em fluxos de trabalho n8n com descoberta inteligente de modelos.

Ferramentas MCP Disponíveis

Ferramentas Principais (7 ferramentas)

tools_documentation - Obtenha documentação para qualquer ferramenta MCP (COMEÇE AQUI!)
search_nodes - Pesquisa de texto completo em todos os nós. Use source: 'community'|'verified' para nós da comunidade, includeExamples: true para configurações
get_node - Ferramenta unificada de informações de nós com vários modos:
- Modo Info (padrão): detail: 'minimal'|'standard'|'full', includeExamples: true
- Modo Docs: mode: 'docs' - Documentação em markdown legível por humanos
- Pesquisa de propriedades: mode: 'search_properties', propertyQuery: 'auth'
- Versões: mode: 'versions'|'compare'|'breaking'|'migrations'
validate_node - Validação unificada de nós:
- mode: 'minimal' - Verificação rápida de campos obrigatórios (<100ms)
- mode: 'full' - Validação abrangente com perfis (mínimo, runtime, amigável para IA, estrito)
validate_workflow - Validação completa de fluxo de trabalho, incluindo validação de Agente de IA
search_templates - Pesquisa unificada de modelos:
- searchMode: 'keyword' (padrão) - Pesquisa de texto com parâmetro query
- searchMode: 'by_nodes' - Encontre modelos usando nodeTypes específicos
- searchMode: 'by_task' - Modelos selecionados para tipos comuns de task
- searchMode: 'by_metadata' - Filtrar por complexity, requiredService, targetAudience
get_template - Obtenha o JSON completo do fluxo de trabalho (modos: nodes_only, structure, full)

Ferramentas de Gerenciamento n8n (21 ferramentas - Requer Configuração de API)

Estas ferramentas requerem N8N_API_URL e N8N_API_KEY em sua configuração.

Gerenciamento de Fluxos de Trabalho

n8n_create_workflow - Crie novos fluxos de trabalho com nós e conexões
n8n_get_workflow - Recuperação unificada de fluxos de trabalho (modos: full, details, structure, minimal)
n8n_update_full_workflow - Atualize todo o fluxo de trabalho (substituição completa)
n8n_update_partial_workflow - Atualize o fluxo de trabalho usando operações de diff
n8n_delete_workflow - Exclua fluxos de trabalho permanentemente
n8n_list_workflows - Liste fluxos de trabalho com filtragem e paginação
n8n_validate_workflow - Valide fluxos de trabalho no n8n por ID
n8n_autofix_workflow - Corrija automaticamente erros comuns de fluxo de trabalho
n8n_workflow_versions - Histórico de versões, diff e rollback em dois históricos: source: 'local' (os snapshots que o n8n-mcp tira antes de alterar um fluxo de trabalho, o padrão) e source: 'native' (o histórico de fluxo de trabalho do próprio n8n, incluindo edições de interface — precisa de N8N_MCP_ACCESS_TOKEN e da configuração "Disponível no MCP" do fluxo de trabalho)
n8n_deploy_template - Implante modelos do n8n.io diretamente em sua instância com correção automática

Descoberta de Recursos de Nós

n8n_explore_node_resources - Resolva o dropdown dinâmico (loadOptions) de um nó ou a pesquisa de localizador de recursos (listSearch) — canais do Slack, abas do Google Sheets, listas de modelos — usando uma credencial real, para que as configurações de fluxo de trabalho usem IDs existentes em vez de inventados. Requer N8N_MCP_ACCESS_TOKEN (consulte Configuração Oficial do MCP)

Gerenciamento de Execuções

n8n_test_workflow - Execute um fluxo de trabalho. method: 'auto' (padrão) o aciona via HTTP através de seu webhook/formulário/chat trigger; method: 'prepare'/'pinned'/'direct' executam fluxos de trabalho que não têm esse trigger através do próprio servidor MCP do n8n (precisa de N8N_MCP_ACCESS_TOKEN e da configuração "Disponível no MCP" do fluxo de trabalho)
n8n_executions - Gerenciamento unificado de execuções (listar, obter, excluir)
n8n_evaluations - Execute e leia execuções de teste de avaliação (liste execuções, métricas agregadas, resultados por caso no n8n 2.30+; acione e cancele no 2.32+)

Gerenciamento de Pastas

n8n_manage_folders - Gerencie pastas de fluxos de trabalho (criar, listar, obter, renomear, mover, excluir; n8n 2.19+). Coloque fluxos de trabalho em pastas via n8n_create_workflow's parentFolderId ou n8n_update_partial_workflow's moveToFolder operation (n8n 2.32+)

Gerenciamento de Tabelas de Dados

n8n_manage_datatable - Gerencie tabelas de dados, linhas e colunas do n8n (listar, obter, criar, atualizar, excluir; addColumn/deleteColumn/renameColumn alteram as colunas de uma tabela existente através do próprio servidor MCP do n8n e precisam de N8N_MCP_ACCESS_TOKEN)

Gerenciamento de Credenciais

n8n_manage_credentials - Gerencie credenciais do n8n (listar, obter, criar, atualizar, excluir, getSchema)

Segurança e Auditoria

n8n_audit_instance - Auditoria de segurança combinando a API de auditoria integrada do n8n com varredura profunda de fluxos de trabalho

Agentes

n8n_manage_agents - Gerencie Agentes n8n (assistentes persistidos com modelo, instruções, ferramentas, habilidades, tarefas, memória e canais) através do servidor MCP em nível de instância do n8n. Requer N8N_MCP_ACCESS_TOKEN e n8n 2.34+ com o módulo de agentes (consulte Configuração Oficial do MCP). Este não é o nó de fluxo de trabalho AI Agent — use get_node para isso

Ferramentas de Sistema

n8n_health_check - Verifique a conectividade e os recursos da API do n8n, incluindo o status de officialMcp quando N8N_MCP_ACCESS_TOKEN está configurado
n8n_list_catalog - Liste projetos ou tags em nível de instância; recorre ao servidor MCP em nível de instância do n8n para projetos de equipe quando a API Pública não os expõe

Implantação Somente Leitura

Para ambientes sensíveis à governança, use ambas as variáveis de ambiente juntas. Desative completamente ferramentas que são de escrita/destrutivas ou que lidam com dados sensíveis (n8n_manage_credentials e n8n_manage_datatable também oferecem operações de leitura, mas são removidas inteiramente aqui porque até mesmo leituras expõem material sensível):

DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable

Para ferramentas que agrupam operações de leitura e escrita sob um único nome, bloqueie apenas as operações destrutivas enquanto mantém list e get. Use isso em vez de uma entrada DISABLED_TOOLS completa onde as operações de leitura da ferramenta são aceitáveis — as entradas n8n_manage_datatable e n8n_test_workflow abaixo são a alternativa para remover essas ferramentas inteiramente como acima. O exemplo nomeia cada operação de escrita de cada ferramenta que possui uma:

DISABLED_TOOL_OPERATIONS=n8n_executions:delete;n8n_test_workflow:auto,trigger,pinned,direct,expose;n8n_evaluations:run,cancel;n8n_manage_folders:create,rename,move,delete;n8n_workflow_versions:delete,rollback,prune,expose;n8n_manage_agents:create,mutate,call,publish,unpublish,revert,delete,update_integration;n8n_manage_datatable:createTable,updateTable,deleteTable,insertRows,updateRows,upsertRows,deleteRows,addColumn,deleteColumn,renameColumn

Dois detalhes são fáceis de esquecer ao escrever sua própria lista. Para n8n_test_workflow, todos os quatro de auto, trigger, pinned e direct executam o fluxo de trabalho (um method omitido ou em branco conta como auto), deixando apenas o prepare somente leitura. E expose não é um valor de nenhum parâmetro de operação: é a escrita de consentimento exposeToMcp de n8n_test_workflow e n8n_workflow_versions, que habilita a configuração "Disponível no MCP" de um fluxo de trabalho. Omitir expose deixa essa escrita acessível.

Combine com uma chave de API do n8n somente leitura (Configurações → API em sua instância do n8n) para defesa em profundidade. Consulte Receita de Implantação Somente Leitura para o guia completo de configuração.

Documentação

Guia de Self-Hosting - Instalação via npx, Docker, Railway e local
Segurança e Hardening - Modelo de confiança, opções de hardening, restrições de workflow
Guia de Implantação do n8n - Implantação em produção com n8n
Configuração do Banco de Dados - Adaptadores SQLite e otimização de memória
Privacidade e Telemetria - O que coletamos e como optar por não participar
Operações de Diff de Workflow - Atualizações de workflow eficientes em tokens
Implantação via HTTP - Configuração de servidor remoto
Configuração Oficial do MCP - Conecte o n8n-mcp ao servidor MCP de nível de instância do n8n para descoberta de Agents e recursos de nós
Log de Alterações - Histórico completo de versões

Licença

Licença MIT - consulte LICENSE para detalhes.

Contribuindo

Consulte CONTRIBUTING.md para configuração de desenvolvimento, testes e diretrizes de contribuição.

Agradecimentos

Consulte Agradecimentos para créditos e atribuição de modelos.

Feito com carinho para a comunidade n8n

💼 Precisa que seja construído para você?

Trabalhe com AiAdvisors — auditorias, construções e operações de automação n8n, gerenciado pelo autor do n8n-mcp e n8n-skills.