Auto-Hospedagem do n8n e Construção de Fluxos de Trabalho com Claude

n8n é uma ferramenta de automação de fluxo de trabalho — do tipo auto-hospedável, em gráfico de nós, onde você conecta um agendamento a uma chamada HTTP para uma gravação em banco de dados e ele roda sem você. Normalmente, você constrói esses gráficos arrastando caixas por uma tela. Eu fiz algo diferente: executei o n8n no Docker na minha própria máquina, registrei-o com o Claude Code como um servidor MCP e então construí três fluxos de trabalho reais ao descrevê-los para o agente, que criou e editou os nós programaticamente. A tela se tornou um lugar que eu ia para verificar, não um lugar que eu ia para construir.

O que é

A instalação em si é deliberadamente chata. Imagem oficial docker.n8n.io/n8nio/n8n, um contêiner chamado n8n, porta 5678, um volume nomeado n8n_data:/home/node/.n8n para que os fluxos de trabalho e credenciais sobrevivam a uma reconstrução do contêiner. Eu escolhi o Docker em vez de uma instalação nativa ou uma instalação WSL especificamente porque o estado do n8n é irritante de realocar depois e um volume nomeado torna a pergunta "onde isso vive" uma questão com uma resposta.

A parte que torna isso interessante é a conexão. O n8n envia um servidor MCP em nível de instância — ative-o nas Configurações, e a instância expõe sua própria API como ferramentas de agente. Eu o registrei no .claude.json com escopo de projeto como n8n-local: transporte http, endpoint http://localhost:5678/mcp-server/http, autenticação Bearer usando uma chave de API do n8n.

Uma armadilha de nomenclatura que vale a pena destacar, porque eu a defini e então me confundi com ela: eu já tinha uma entrada MCP global chamada n8n apontando para uma instância hospedada do n8n Cloud. Então n8n e n8n-local são dois servidores diferentes apontando para duas instalações diferentes do n8n. Cada momento de "por que meu fluxo de trabalho não está lá" no primeiro dia voltou a isso.

Com o servidor conectado, o ciclo de construção para um fluxo de trabalho se parece com isto:

1. get_sdk_reference — o agente lê como o SDK de fluxo de trabalho realmente funciona
2. search_nodes / get_node_types — encontra o nó certo e sua verdadeira forma de parâmetro
3. create_workflow_from_code — constrói o gráfico
4. update_workflow(operations) — corrige nós individuais à medida que as coisas são corrigidas

Essa ordem importa. O modo de falha quando um agente constrói fluxos de trabalho do n8n é inventar com confiança um parâmetro de nó que não existe, e a correção é entediante e simples: faça-o ler a definição real do tipo do nó antes de escrever o nó.

Três fluxos de trabalho

AI Digest (20 nós, diariamente às 07:00 America/New_York) puxa seis feeds RSS de notícias de IA — Anthropic, Simon Willison, Latent Space, n8n, Zapier, Hacker News — marca cada item com sua fonte, mescla todos os seis fluxos, filtra para as últimas 24 horas e anexa novos itens a um banco de dados do Notion, pulando qualquer coisa que já esteja lá. O teste de ponta a ponta escreveu 13 linhas cobrindo todas as seis fontes; reexecutá-lo imediatamente adicionou exatamente 0, que é o número que você deseja de um caminho de deduplicação.

Agente de Diagnóstico de Encanamento é um formulário da web que retorna um diagnóstico estruturado. Gatilho de Formulário → um nó de Código que valida a entrada e escaneia a descrição em busca de palavras-chave de emergência (inundação, canos estourados, cheiro de gás, refluxo de esgoto…) → uma Cadeia LLM Básica executando o Ollama local qwen2.5:7b-instruct atrás de um analisador de saída estruturada → uma tabela de dados que registra o caso → uma página de conclusão que renderiza o relatório. O analisador impõe um esquema fixo — identificação do problema, causas classificadas com probabilidades, ações imediatas, se precisa de um profissional, urgência, uma faixa de custo, dicas de prevenção — porque pedir a um modelo de 7B por JSON e chamar JSON.parse no resultado é um jogo de azar. Eu verifiquei isso com três cenários, um caminho de falha forçada e uma submissão real de navegador; o caso de cheiro de gás corretamente liderou com o banner de emergência vermelho.

Monitor de Cobre SDWIS verifica semanalmente (segundas-feiras, 08:00) os dados de conformidade da água potável da EPA para um sistema público de água específico, junta duas chamadas de API em uma tendência e me envia um e-mail apenas se uma condição de alerta disparar. Era um port: o original estava no n8n Cloud, cujo conector queria um fluxo de OAuth interativo que eu não consegui completar a partir de uma sessão de agente. Reconstruí-lo fresco na instância local foi mais rápido do que corrigir a autenticação. Testado ao vivo contra dados reais da EPA para PWSID FL4504393, retornou copperPresent: false, pb90Latest: 0.0014, pb90Max: 0.002 — uma correspondência exata ao que a versão em nuvem havia produzido, que é como eu soube que o port era fiel.

Os problemas

Nós de ação silenciosamente sobrescrevem $json. Este é o que custou tempo real e o que eu diria a qualquer um que esteja construindo fluxos de trabalho do n8n primeiro. No monitor de cobre, o ramo de alerta vai Gmail-enviar → registrar a linha. O nó de registro leu $json para seus campos, que é a coisa óbvia a escrever. Mas depois de um nó do Gmail, $json é a resposta do Gmail — um objeto com id e threadId e nada mais. Os dados anteriores foram perdidos. Cada linha registrada no caminho de alerta teria sido toda nula.

A correção é uma linha de disciplina: após qualquer nó de ação cuja saída você não deseja realmente, referencie explicitamente o nó de origem.

// errado — $json agora é a resposta de envio do Gmail
const value = $json.pb90Latest;

// certo — nomeie o nó que você realmente quer dizer
const value = $('Normalize').item.json.pb90Latest;

O que importa mais do que a correção é como isso surgiu. A condição de alerta deve ser falsa quase sempre — esse é o objetivo de um monitor. Então o caminho feliz testou limpo e o bug estava completamente invisível. Eu só o encontrei forçando temporariamente a condição verdadeira, executando-o, inspecionando a linha registrada, vendo todos nulos, corrigindo, re-verificando e então restaurando a lógica real antes de ativar. Teste o ramo que não deveria disparar. Caminhos de alerta, manipuladores de erro e alternativas são exatamente onde essa classe de bug vive, porque a operação normal nunca os toca.

n8n no Docker não pode acessar o Ollama do seu host em localhost. Dentro do contêiner, localhost é o contêiner. A URL base das credenciais do Ollama deve ser http://host.docker.internal:11434. O sintoma é enganoso — você recebe um Express Cannot POST /api/chat, que parece um bug do n8n ou um caminho de endpoint errado em vez de "você está falando com a máquina errada."

Há uma variante mais complicada por baixo. Eu tinha dois daemons do Ollama nesta máquina — um do WSL, um nativo do Windows, versões diferentes — e o que o contêiner podia ver não era o que meu CLI host estava falando. Então ollama list no host mostrava um modelo que o fluxo de trabalho não conseguia encontrar. A única verificação confiável é perguntar de dentro do contêiner:

docker exec n8n wget -qO- http://host.docker.internal:11434/api/tags

Se o modelo que você deseja não estiver naquela saída, nada do que você faz no t