Crie Workflow n8n com Código Claude Usando n8n-MCP

Alguma vez desejou poder simplesmente pedir a uma IA para construir um fluxo de trabalho de automação e tê-lo pronto no n8n? E se o seu assistente de IA pudesse criar, atualizar e executar fluxos de trabalho n8n diretamente sem copiar JSON manualmente ou arrastar nós? Bem-vindo ao n8n-MCP com Claude Code, um sistema que transforma linguagem natural em automação de fluxo de trabalho real e implementável.

O Que É n8n-MCP e Por Que Você Deveria Se Importar?

n8n-MCP é um servidor de Protocolo de Contexto de Modelo que expõe seus fluxos de trabalho do n8n como ferramentas executáveis para assistentes de IA como o Claude Code. Em vez de executar fluxos de trabalho manualmente através da interface do usuário do n8n ou da API REST, você descreve o que deseja em linguagem natural, e o Claude Code invoca o fluxo de trabalho correto, passa os parâmetros e retorna os resultados.

A mudança é sutil, mas massiva. Assistentes de codificação de IA tradicionais geram código. Com n8n-MCP, eles executam fluxos de trabalho. Seu fluxo de trabalho de pesquisa na web se torna uma ferramenta. Seu pipeline de enriquecimento de dados se torna uma ferramenta. Seu fluxo de notificação do Slack se torna uma ferramenta. O Claude Code se torna um agente que orquestra sistemas reais, não apenas um gerador de código.

Para desenvolvedores que constroem ferramentas internas ou automatizam pesquisas, isso significa que você pode:

Consultar APIs em tempo real sem escrever chamadas fetch
Acionar pipelines de dados a partir do seu editor
Validar dados externos antes de fazer commit do código
Construir agentes personalizados adaptados à sua stack

O protocolo é simples: n8n-MCP traduz as chamadas de ferramenta do Claude Code em requisições HTTP para seus nós de webhook do n8n, e então organiza as respostas de volta para o Claude. Você obtém todo o poder das mais de 400 integrações do n8n dentro do seu fluxo de trabalho CLI.

💡

Quer uma ótima ferramenta de Teste de API que gera Documentação de API bonita?

Quer uma plataforma integrada e All-in-One para sua Equipe de Desenvolvedores trabalhar em conjunto com produtividade máxima?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!

botão

Passo 1: Instalar o n8n e Criar um Fluxo de Trabalho de Pesquisa na Web

Primeiro, você precisa de uma instância n8n em execução. Para desenvolvimento local, o Docker é o mais rápido.

# Criar um diretório para os dados do n8n
mkdir ~/n8n-data && cd ~/n8n-data

# Iniciar n8n com Docker
docker run -d --name n8n \
  -p 5678:5678 \
  -v $(pwd):/home/node/.n8n \
  --restart unless-stopped \
  docker.n8n.io/n8nio/n8n

Abra http://localhost:5678 e complete a configuração. Crie uma conta de administrador.

usando n8n auto-hospedado com docker desktop

Construir o Fluxo de Trabalho de Pesquisa na Web

Clique em Novo Fluxo de Trabalho
Adicione um nó Webhook (gatilho)

Método HTTP: POST
Caminho: web-search
Modo de Resposta: Quando o Último Nó Terminar

3. Adicione um nó HTTP Request

URL: https://duckduckgo.com/html/?q={{ $json.query }}
Método: GET

4. Adicione um nó HTML Extract

Propriedade de Dados: data
Valores de Extração:
Chave: results
Seletor CSS: .result__a
Valor de Retorno: Texto

5. Adicione um nó Set para formatar a saída

Valores a Definir:
results: {{ $json.results }}

6. Conecte webhook → HTTP → HTML Extract → Set

7. Ative o fluxo de trabalho (alternar no canto superior direito)

Teste-o manualmente:

curl -X POST http://localhost:5678/webhook/web-search \
  -H "Content-Type: application/json" \
  -d '{"query":"trending AI topics 2026"}'

Você deverá ver um array JSON de resultados de pesquisa. Este fluxo de trabalho está agora pronto para exposição via MCP.

Passo 2: Instalar e Configurar o n8n-MCP

O servidor n8n MCP faz a ponte entre n8n e Claude Code. Instale-o globalmente ou em um diretório de projeto.

# Clonar o repositório n8n-MCP
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

# Instalar dependências
npm install

# Construir o projeto
npm run build

Configurar Variáveis de Ambiente

Crie um arquivo .env no diretório n8n-MCP:

# .env
N8N_API_URL=http://localhost:5678
N8N_API_KEY=n8n_api_key_aqui

Obtenha sua chave de API do n8n em Configurações → API na interface do usuário do n8n. Se você não vir uma seção de chave de API, pode ser necessário ativá-la via variável de ambiente ao iniciar o n8n:

# Parar e reiniciar n8n com API habilitada
docker stop n8n
docker rm n8n

docker run -d --name n8n \
  -p 5678:5678 \
  -v $(pwd):/home/node/.n8n \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=suasenha \
  --restart unless-stopped \
  docker.n8n.io/n8nio/n8n

Agora gere uma chave de API na interface do usuário.

Iniciar o Servidor MCP

# Iniciar o servidor MCP
npm start

Por padrão, ele é executado em http://localhost:3001. Você deve ver:

n8n MCP Server running on http://localhost:3001
Ferramentas disponíveis: [ 'web-search' ]

O servidor descobre automaticamente fluxos de trabalho com caminhos de webhook e os expõe como ferramentas.

Passo 3: Configurar o Claude Code para Usar o n8n-MCP

O Claude Code usa um arquivo de configuração para descobrir ferramentas MCP. Crie ou edite sua configuração do Claude Code.

# Encontrar o diretório de configuração do Claude Code
# macOS: ~/Library/Application Support/Claude Code
# Linux: ~/.config/Claude Code
# Windows: %APIDATA%/Claude Code

cd ~/Library/Application\ Support/Claude Code

Crie um arquivo chamado mcp.json:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/n8n-mcp/dist/index.js"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "sua_n8n_api_key"
      }
    }
  }
}

Crítico: Use caminhos absolutos para args. Caminhos relativos falham quando o Claude Code inicia o processo.

Verificar a Conexão

Inicie o Claude Code em seu projeto:

claude

Uma vez carregado, digite:

/list-tools

Você deve ver:

Ferramentas disponíveis:
- n8n:web-search (Executa o fluxo de trabalho web-search)

Se a ferramenta não aparecer, verifique os logs:

# Em outro terminal, acompanhe os logs do Claude Code
tail -f ~/Library/Application\ Support/Claude\ Code/logs/mcp.log

Problemas comuns:

ENOENT: Caminho incorreto para n8n-mcp/dist/index.js
ECONNREFUSED: n8n não está em execução em localhost:5678
401: N8N_API_KEY incorreta

Passo 4: Aplicação Prática—Pesquisa na Web a Partir do Claude Code

Agora a mágica acontece. Em qualquer diretório de projeto, inicie o Claude Code e execute:

claude

No prompt, digite:

Usando a ferramenta de pesquisa na web no n8n, procure tópicos de IA em alta em 2026

O Claude Code irá:

Reconhecer a ferramenta n8n:web-search
Analisar sua intenção ("tópicos de IA em alta em 2026")
Extrair o parâmetro de consulta
Chamar o servidor MCP
O servidor MCP chama o webhook do n8n
n8n executa o fluxo de trabalho e retorna os resultados
MCP retorna JSON ao Claude Code
Claude Code formata e exibe a resposta

Exemplo de Sessão

$ claude
> Usando a ferramenta de pesquisa na web no n8n, procure tópicos de IA em alta em 2026

Vou ajudá-lo a pesquisar tópicos de IA em alta em 2026 usando a ferramenta de pesquisa na web do n8n.

Chamando n8n:web-search com a consulta: "trending AI topics 2026"

A ferramenta retornou 8 resultados:
1. "Avanços em IA Quântica em 2026: O Que os Desenvolvedores Precisam Saber"
2. "LLMs Multimodais: Além de Texto e Imagens"
3. "Implantação de Edge AI: Reduzindo Custos de Nuvem em 40%"
4. "Agentes de Revisão de Código de IA: Aumento da Adoção em Empresas"
5. "Aprendizado Federado: Treinamento de IA com Privacidade em Primeiro Lugar"
6. "Geração de Dados Sintéticos: Debate Qualidade vs. Quantidade"
7. "Detecção de Alucinações de IA: Novas Ferramentas de Código Aberto"
8. "Computação Neuromórfica: Tendências de Co-Design Hardware-Software"

Com base nestes resultados, aqui estão os principais tópicos de IA em alta em 2026:
- A integração da IA Quântica tornando-se prática para desenvolvedores
- Modelos multimodais estendendo-se além de texto/imagens para áudio/vídeo
- Implantação de Edge AI para redução de custos
- Agentes de IA para revisão de código ganhando tração empresarial
- Aprendizado federado com preservação de privacidade
- Pipelines de dados sintéticos
- Ferramentas de detecção de alucinações
- Avanços em hardware neuromórfico

Enquanto isso, na interface do usuário do n8n, você verá a execução do fluxo de trabalho aparecer em tempo real, provando que o Claude Code o acionou remotamente.

Padrões Avançados: Construindo Fluxos de Trabalho Agênticos

Padrão 1: Enriquecer Dados de Múltiplas Fontes

Crie um fluxo de trabalho que busca um usuário do GitHub e, em seguida, procura seus tweets recentes:

Nó Webhook (enrich-user)
Requisição HTTP → API do GitHub (/users/{{ $json.username }})
Requisição HTTP → API do X (/users/by/username/{{ $json.username }})
Nó Merge (combinar respostas)
Nó Set (formatar objeto final)

Agora no Claude Code:

Enriquecer perfil de usuário para @johndoe usando o fluxo de trabalho enrich-user

O Claude passa automaticamente os parâmetros e recebe dados estruturados.

Padrão 2: Seleção Condicional de Ferramenta

Construa múltiplos fluxos de trabalho e deixe o Claude escolher:

web-search-duckduckgo: Gratuito, mas mais lento
web-search-serpapi: Pago, mas estruturado
web-search-google: Scraper personalizado

No seu prompt:

Pesquise por padrões assíncronos em Python. Use a ferramenta de pesquisa na web mais rápida disponível.

O Claude lê as descrições das ferramentas e escolhe com base na sua instrução.

Padrão 3: Encadeando Fluxos de Trabalho

A saída de um fluxo de trabalho pode acionar outro. Crie:

fetch-data: Obtém dados brutos
analyze-data: Aceita dados, executa análise
summarize-data: Aceita análise, produz resumo

No Claude Code:

Buscar dados de vendas, analisar tendências do primeiro trimestre e resumir os principais insights

O Claude encadeará os três fluxos de trabalho sequencialmente, passando as saídas entre eles.

Não Se Esqueça de Proteger Seus Webhooks

Adicione cabeçalhos de autenticação no n8n:

Edite o nó Webhook
Defina Autenticação: Header Auth
Nome: X-API-Key
Valor: seu-segredo-de-webhook-seguro

Atualize o arquivo .env para n8n-MCP:

N8N_WEBHOOK_SECRET=seu-segredo-de-webhook-seguro

Modifique o servidor MCP para passar cabeçalhos (você precisará editar src/index.ts):

// Na função de execução da ferramenta
const response = await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.N8N_WEBHOOK_SECRET
  },
  body: JSON.stringify(parameters)
});

Controle de Taxa (Rate Limiting)

Adicione uma camada de cache Redis para prevenir abusos:

// No n8n-MCP, antes de chamar o webhook
import Redis from 'ioredis';
const redis = new Redis();

const rateLimitKey = `rate_limit:${toolName}:${Date.now() / 60000}`;
const count = await redis.incr(rateLimitKey);
if (count > 10) { // 10 chamadas por minuto
  throw new Error('Limite de taxa excedido');
}
await redis.expire(rateLimitKey, 60);

Tratamento de Erros

Aprimore o servidor MCP para retornar erros estruturados:

try {
  const response = await fetch(webhookUrl, {...});
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  return await response.json();
} catch (error) {
  return {
    error: error.message,
    status: 'failed'
  };
}

O Claude Code exibirá o erro e poderá tentar novamente automaticamente.

Conclusão

n8n-MCP transforma o n8n de uma ferramenta de automação manual em um backend agêntico programável para o Claude Code. Você constrói fluxos de trabalho visualmente, os expõe como ferramentas e orquestra tarefas complexas com linguagem natural. A configuração é direta: instale o n8n, crie um fluxo de trabalho de webhook, execute o servidor MCP e configure o Claude Code. O resultado é um agente de IA personalizado que conhece sua stack e pode executar tarefas do mundo real. E quando você construir APIs nesses fluxos de trabalho, teste-as com o Apidog—porque até mesmo agentes de IA precisam de contratos confiáveis.

botão