n8n Workflow Builder

Um servidor MCP para gerenciar workflows do n8n através de sua API.

GitHub

229

Experimente este MCPPatrocinado

Documentação

Servidor MCP n8n Workflow Builder

Automação de Workflows com IA Através de Linguagem Natural

Crie, gerencie e monitore workflows do n8n usando Claude AI e Cursor IDE através do Model Context Protocol

Recursos • Início Rápido • Documentação • Exemplos • Referência da API

AI-Powered Workflow Builder - Build n8n workflows with natural language

🎯 O que é isto?

O Servidor MCP n8n Workflow Builder transforma a automação de workflows ao permitir que você crie e gerencie workflows do n8n através de IA conversacional. Chega de edição manual de JSON ou navegação complexa na interface — basta descrever o que você precisa em linguagem natural e deixar a IA construir para você.

O Problema que Ele Resolve

❌ Criação manual de workflows é demorada e propensa a erros
❌ Edição complexa de JSON exige conhecimento técnico profundo
❌ Alternar entre IDE e interface do n8n interrompe seu fluxo de desenvolvimento
❌ Gerenciar múltiplos ambientes n8n (dev, staging, prod) é tedioso

A Solução

✅ Crie workflows conversacionalmente usando Claude AI ou Cursor IDE
✅ Interface em linguagem natural — descreva workflows em português simples
✅ Suporte a múltiplas instâncias — gerencie dev, staging e produção de um só lugar
✅ 17 ferramentas poderosas — gerenciamento completo do ciclo de vida de workflows
✅ Fique no seu IDE — sem necessidade de alternar de contexto

✨ Recursos Principais

🤖 Criação de Workflows com IA

Crie workflows complexos do n8n simplesmente descrevendo o que você precisa. Claude AI e Cursor IDE entendem sua intenção e geram workflows prontos para produção.

🌍 Gerenciamento de Múltiplas Instâncias

Gerencie facilmente múltiplos ambientes n8n (produção, staging, desenvolvimento) a partir de um único servidor MCP com roteamento inteligente de instâncias.

🛠️ 17 Ferramentas Abrangentes

Cobertura completa do ciclo de vida de workflows:

8 Ferramentas de Workflow — Criar, atualizar, excluir, ativar, executar
4 Ferramentas de Execução — Monitorar, tentar novamente, analisar execuções
5 Ferramentas de Tags — Organizar e categorizar workflows
6 Ferramentas de Credenciais (Epic 2) — Gerenciamento seguro de credenciais

💬 Interface em Linguagem Natural

Sem necessidade de edição de JSON. Crie workflows assim:

"Crie um workflow de webhook que valide e-mails de clientes, envie uma notificação no Slack e armazene dados no PostgreSQL"

🔒 Seguro por Design

Proteção integrada de credenciais
Criptografia de chaves de API
Configuração segura de múltiplas instâncias
Nunca expõe dados sensíveis em logs

📚 Documentação Abrangente

Mais de 38 páginas de documentação com guias e tutoriais
Exemplos interativos e padrões de workflow
Guias de solução de problemas e FAQs
Referência da API com documentação completa das ferramentas

🚀 Início Rápido

Pré-requisitos

Node.js v14+ (v18+ recomendado)
npm v7+
Instância do n8n com acesso à API (testado com n8n v1.82.3+)
Claude Desktop ou Cursor IDE

Instalação

# Install globally via npm
npm install -g @kernel.salacoste/n8n-workflow-builder

# Verify installation
npx @kernel.salacoste/n8n-workflow-builder --version

Configuração

Opção 1: Múltiplas Instâncias (Recomendado)

Crie .config.json na raiz do seu projeto:

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_production_api_key"
    },
    "staging": {
      "n8n_host": "https://staging.n8n.example.com",
      "n8n_api_key": "your_staging_api_key"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "your_dev_api_key"
    }
  },
  "defaultEnv": "development"
}

Opção 2: Instância Única (Compatível com Versões Anteriores)

Crie o arquivo .env:

N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key

Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

Reinicie o Claude Desktop e você estará pronto para começar! 🎉

Integração com Cursor IDE

Adicione ao .cursor/mcp.json no seu espaço de trabalho:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

📖 Documentação Completa

Explore nosso site de documentação abrangente:

🌐 Documentação Completa

Links Rápidos

Seção	Descrição
🚀 Tutorial de Início Rápido	Crie seu primeiro workflow em 5 minutos
📦 Guia de Instalação	Instruções detalhadas de configuração
🔧 Configuração	Configuração de múltiplas instâncias e ambientes
🛠️ Referência da API	Documentação completa das ferramentas
🏗️ Configuração de Múltiplas Instâncias	Gerencie múltiplos ambientes n8n
💡 Padrões de Uso	Melhores práticas e padrões de conversa
🐛 Solução de Problemas	Problemas comuns e soluções

🎨 Exemplos

Exemplo 1: Criar um Workflow de Webhook

Você:

Crie um workflow de webhook no staging que:

Receba requisições POST em /customer-signup

Valide os campos de e-mail e nome

Envie e-mail de boas-vindas via Gmail

Armazene o cliente no PostgreSQL

Claude: ✅ Cria workflow completo com nós de validação, e-mail e banco de dados

Exemplo 2: Gerenciamento de Workflows em Múltiplas Instâncias

Você:

Liste todos os workflows ativos em produção que não foram executados nos últimos 7 dias

Claude: 📊 Analisa o ambiente de produção e identifica workflows obsoletos

Exemplo 3: Depurar Execuções com Falha

Você:

Depure o workflow 456 em produção — ele está falhando com erros

Claude: 🔍 Recupera o histórico de execuções, identifica a causa raiz e sugere correções

Exemplo 4: Gerenciamento de Credenciais

Você:

Mostre-me o schema para credenciais OAuth2 e depois ajude-me a criar credenciais para a API do Google Sheets

Claude: 🔐 Recupera o schema de credenciais e orienta você na criação segura de credenciais

🛠️ Referência das Ferramentas MCP

Gerenciamento de Workflows (8 ferramentas)

Ferramenta	Descrição	Exemplo de Uso
`list_workflows`	Listar todos os workflows com filtros	"Mostre-me workflows ativos em produção"
`get_workflow`	Recuperar detalhes completos do workflow	"Obtenha o workflow 123 do staging"
`create_workflow`	Criar novos workflows do zero	"Crie um workflow de relatório diário"
`update_workflow`	Modificar workflows existentes	"Adicione tratamento de erros ao workflow 456"
`delete_workflow`	Remover workflows	"Exclua o workflow 789"
`activate_workflow`	Ativar execução de workflows	"Ative o workflow 123"
`deactivate_workflow`	Desativar execução de workflows	"Desative o workflow 456"
`execute_workflow`	Acionar manualmente execuções de workflows	"Execute o workflow 789 com dados de teste"

Gerenciamento de Execuções (4 ferramentas)

Ferramenta	Descrição	Exemplo de Uso
`list_executions`	Visualizar histórico de execuções com filtros	"Mostre execuções com falha de hoje"
`get_execution`	Informações detalhadas de execução	"Obtenha detalhes da execução 9876"
`delete_execution`	Remover registros de execução	"Exclua execuções de teste antigas"
`retry_execution`	Tentar novamente execuções de workflows com falha	"Tente novamente a execução 9876"

Gerenciamento de Tags (5 ferramentas)

Ferramenta	Descrição	Exemplo de Uso
`list_tags` / `get_tags`	Recuperar todas as tags de workflows	"Mostre todas as tags de workflows"
`get_tag`	Obter informações de uma tag específica	"Obtenha detalhes da tag 'email-automation'"
`create_tag`	Criar tags de organização de workflows	"Crie a tag 'customer-workflows'"
`update_tag`	Modificar informações de tags	"Renomeie a tag para 'legacy-workflows'"
`delete_tag`	Remover tags de workflows	"Exclua a tag 'deprecated'"

Gerenciamento de Credenciais (6 ferramentas — Epic 2)

Ferramenta	Descrição	Exemplo de Uso
`get_credential_schema`	Obter schema JSON do tipo de credencial	"Mostre o schema para httpBasicAuth"
`list_credentials`	Orientação de segurança (bloqueado pela API do n8n)	"Listar orientações de credenciais"
`get_credential`	Orientação de segurança (bloqueado pela API do n8n)	"Obter orientação de credenciais"
`create_credential`	Criar credenciais com validação de schema	"Crie credenciais OAuth2 do Gmail"
`update_credential`	Orientação de imutabilidade (DELETE + CREATE)	"Atualizar orientação de credenciais"
`delete_credential`	Remover credenciais permanentemente	"Exclua a credencial 123"

🏗️ Arquitetura de Múltiplas Instâncias

Gerencie múltiplos ambientes n8n com roteamento inteligente:

┌─────────────────────────────────────┐
│   MCP Server (Single Instance)     │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐  ┌──────────┐       │
│  │ ConfigLoader│ EnvironmentMgr   │
│  └──────────┘  └──────────┘       │
│         │            │             │
│         ▼            ▼             │
│  ┌─────────────────────────┐      │
│  │   Instance Routing      │      │
│  └─────────────────────────┘      │
│         │                          │
└─────────┼──────────────────────────┘
          │
    ┌─────┴─────┬─────────────┬──────────────┐
    │           │             │              │
    ▼           ▼             ▼              ▼
┌────────┐  ┌────────┐   ┌────────┐    ┌────────┐
│  Dev   │  │Staging │   │  Prod  │    │Custom  │
│ n8n    │  │  n8n   │   │  n8n   │    │  n8n   │
└────────┘  └────────┘   └────────┘    └────────┘

Benefícios:

✅ Um único servidor MCP gerencia todos os ambientes
✅ Roteamento automático de instâncias com base no contexto
✅ Chaves de API separadas por ambiente
✅ Alternância fácil entre ambientes nas conversas

🎯 Casos de Uso

🚀 Fluxo de Desenvolvimento

Desenvolva no Ambiente de Desenvolvimento: Crie e teste workflows localmente
Implante no Staging: Valide no ambiente de QA
Promova para Produção: Implante com confiança

📊 Operações e Monitoramento

Monitore o status de execuções entre ambientes
Depure workflows com falha com análise detalhada
Acompanhe o desempenho e a confiabilidade dos workflows

🔄 Migração de Workflows

Exporte workflows de uma instância
Importe para outra com adaptação automática
Operações em lote entre ambientes

📝 Documentação e Aprendizado

Gere documentação de workflows automaticamente
Aprenda padrões do n8n com orientação de IA
Explore exemplos e modelos de workflows

🔒 Segurança e Melhores Práticas

Proteção de Credenciais

✅ .config.json excluído automaticamente do git via .gitignore
✅ Chaves de API nunca são registradas em logs (apenas os primeiros 20 caracteres são exibidos)
✅ Credenciais criptografadas pela API do n8n
✅ Sem dados sensíveis em pacotes npm

Segurança de Múltiplas Instâncias

✅ Chaves de API separadas por ambiente
✅ Chaves de produção isoladas do desenvolvimento
✅ Validação de instância antes de chamadas de API

Operações Seguras

⚠️ IMPORTANT: Be careful with destructive operations!

- Always test in development first
- Use get_workflow to backup before modifications
- Review workflow details before deletion
- Enable debug mode for troubleshooting

🐛 Solução de Problemas

Problemas Comuns

Falha na Conexão do Servidor MCP

Sintomas: Claude/Cursor não consegue encontrar as ferramentas do n8n

Soluções:

Reinicie o Claude Desktop / Cursor IDE
Verifique a sintaxe de claude_desktop_config.json / .cursor/mcp.json
Confirme que a instância do n8n está acessível
Ative o modo de depuração: DEBUG=true no ambiente

Guia Completo de Depuração

Erros 404 ao Chamar a API do n8n

Sintomas: "Request failed with status code 404"

Soluções:

Verifique se n8n_host usa a URL base (ex.: https://n8n.example.com)
NÃO inclua o sufixo /api/v1 (o servidor o adiciona automaticamente)
Verifique se a chave de API do n8n tem as permissões corretas
Teste a conectividade: curl https://your-n8n-instance.com/api/v1/workflows

Guia de Configuração

Falha na Ativação do Workflow

Sintomas: "Workflow cannot be activated without valid trigger"

Soluções:

Garanta que o workflow tenha pelo menos um nó de gatilho (webhook, agendamento, etc.)
manualTrigger NÃO é reconhecido pela API do n8n v1.82.3
O servidor adiciona automaticamente gatilhos válidos se estiverem ausentes

Referência de Erros

Obter Ajuda

📊 Novidades

Versão 0.9.3 (Mais Recente) — Segurança e Documentação

🔒 Correção de Segurança: Impediu que arquivos de log fossem publicados no npm
📦 Otimização do Pacote: Tamanho reduzido para 653KB (de 699KB)
📚 Melhoria na Documentação: Adicionados badges e metadados npm aprimorados
✅ Rotação de Chaves de API: Práticas de segurança atualizadas

Versão 0.9.0 — Conformidade com o Protocolo MCP

✅ Suporte completo ao manipulador de notificações MCP
✅ Corrigido o erro "Method 'notifications/initialized' not found"
📦 Otimização do tamanho do pacote: 1.3MB → 278KB
🏗️ Arquitetura de múltiplas instâncias com roteamento inteligente
🔐 Gerenciamento aprimorado de credenciais com validação de schema

Epic 2 Completo (13/13 Histórias) — Implementação Avançada da API

✅ 17 Ferramentas MCP implementadas (8 workflows + 4 execuções + 5 tags + 6 credenciais)
✅ 100% de taxa de sucesso nos testes em todas as implementações
✅ Mais de 12.000 linhas de documentação com exemplos abrangentes
✅ Qualidade pronta para produção com zero bugs

Ver Changelog Completo

🗺️ Roadmap

✅ Concluído

Operações CRUD de workflow principais
Gerenciamento e monitoramento de execuções
Organização de workflows por tags
Arquitetura multi-instância
Gerenciamento do ciclo de vida de credenciais
Site de documentação abrangente (mais de 38 páginas)
Implantação no GitHub Pages com CI/CD

🚧 Em Andamento

Biblioteca de modelos de workflow
Padrões aprimorados de recuperação de erros
Otimização de desempenho para workflows grandes
Recursos avançados de filtragem e busca

🔮 Planejado

Integração com editor visual de workflows
Controle de versão e reversão de workflows
Desenvolvimento colaborativo de workflows
Análises e insights avançados
Marketplace e compartilhamento de workflows

Sugerir um Recurso

🤝 Contribuindo

Aceitamos contribuições! Veja como você pode ajudar:

Formas de Contribuir

🐛 Reportar Bugs: Criar uma issue
💡 Sugerir Recursos: Abrir uma discussão
📖 Melhorar a Documentação: Envie melhorias de documentação
🔧 Enviar Pull Requests: Corrija bugs ou adicione recursos

Configuração de Desenvolvimento

# Clone repository
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev