Automatize checks repetitivos com n8n local e um agente de IA

Todo desenvolvedor mantém uma lista privada de coisas para re-checar ao longo do dia: PRs esperando review, schedules que podem ter falhado, dashboards em deriva. Nada disso é difícil. Tudo é interrupção — o tipo que quebra foco e ainda assim passa despercebido.

Este post mostra como transformar uma dessas checagens em pipeline automático: o n8n rodando local como máquina de estados, um agente de código conectado pelo servidor MCP do n8n, e um monitor de pull requests que dispara notificação no macOS quando algo muda de fato. Tudo na sua máquina — sem conta em nuvem, sem Docker.

Passo 1: instalar o n8n local sem Docker

A recomendação oficial é Docker, mas para uma máquina pessoal o npm basta e pula uma camada de abstração:

npx --yes --registry=https://registry.npmjs.org n8n

Duas restrições que valem saber antes da primeira execução:

• Versão do Node: a faixa suportada é 20.19 a 24.x. Versões mais novas costumam funcionar, mas a faixa é o que a documentação garante.
• Proxies corporativos de npm: se sua empresa roteia o npm por um proxy de segurança que bloqueia CVEs, alguma dependência transitiva do n8n pode ser recusada. Acrescentar --registry=https://registry.npmjs.org contorna o proxy só naquela instalação.

A primeira execução cria o ~/.n8n: banco SQLite, estado de sessão e — o importante — uma chave de criptografia em ~/.n8n/config. Essa chave cifra toda credencial que você for guardar no n8n. Perdê-la significa perder as credenciais, não apenas um arquivo de config. Copie para um lugar seguro antes de qualquer coisa:

cp ~/.n8n/config ~/.n8n/config.backup-$(date +%Y%m%d)

O editor também vai pedir um cadastro no primeiro acesso pelo navegador. É uma conta de owner local em ~/.n8n — sem registro em nuvem — que protege o editor e os tokens dentro dele.

Passo 2: conectar o servidor MCP ao seu agente de IA

O n8n traz um servidor MCP oficial desde a 2.33. Ele expõe a instância inteira para clientes de IA: pesquisar workflows, ler e editá-los, executá-los, criar e consultar data tables, validar código do Workflow SDK. É a peça que transforma o agente em operador de primeira classe em vez de alguém que você copia JSON.

Habilite na UI:

1. Settings → Instance-level MCP → Enable MCP access.
2. Connect → API key — copie o token gerado.

E aponte o harness do seu agente para o endpoint:

{
  "mcpServers": {
    "n8n": {
      "type": "http",
      "url": "http://localhost:5678/mcp-server/http",
      "headers": {
        "Authorization": "Bearer ${N8N_MCP_TOKEN}"
      }
    }
  }
}

A distinção de credenciais que custa horas

O n8n tem duas superfícies de autenticação, e elas não são intercambiáveis:

• O token de acesso MCP (acima) autentica /mcp-server/http — a superfície de clientes de IA.
• A Public API key, em Settings → n8n API, autentica /api/v1/* — a superfície REST para scripts e CI.

O payload do JWT os diferencia: o claim aud do token MCP é mcp-server-api. Tente usá-lo na REST API e você recebe um 401 seco, sem explicação. Essa distinção sozinha consumiu boa parte de uma tarde minha — uma variável chamada N8N_API_KEY que guarda um token de MCP é uma armadilha que morde duas vezes.

Mais um detalhe dentro dessa armadilha: evite nomear suas próprias variáveis com o prefixo N8N_. O processo do n8n consome variáveis N8N_* como configuração própria, e elas não chegam à execução de comandos dentro dos workflows como se esperaria. Um nome neutro no lugar de N8N_MCP_TOKEN… na verdade, a regra mais limpa é: variáveis de shell para ferramentas externas não devem colidir com o namespace do próprio host.

Passo 3: construir um armazenamento de estado com data tables

Monitores precisam de memória: o que vi da última vez, o que mudou desde então. As data tables do n8n existem exatamente para isso — linhas estruturadas com escopo de projeto, sem banco externo.

Crie uma na aba Data tables. Para um monitor de pull requests:

pr_number | repo | title | head_sha | review_decision
approved_by | comment_count | updated_at

As chaves de comparação são o design. Um head_sha diferente é push novo. Um review_decision ou approved_by diferente é movimentação de review. Um comment_count diferente é alguém falando. Todo o resto engole-se em silêncio.

O node Data Table faz get, insert, update e upsert dentro do workflow com autenticação interna — sem HTTP, sem token, sem credencial para configurar.

Passo 4: montar a checagem — um monitor de pull requests

O grafo do workflow:

Schedule Trigger (15 min)
  → Execute Command: coletar PRs abertos como JSON (gh CLI)
  → Data Table: Get rows (snapshot anterior)
  → Code node: diff atual vs anterior
  → IF algo mudou
      → Execute Command: notificação macOS por mudança
      → Data Table: Insert das novas linhas de snapshot

O coletor é um script pequeno em disco, chamado pelo node Execute Command — lógica determinística não pertence ao inline do workflow. Usa o GitHub CLI que você já tem autenticado:

gh search prs --author @me --state open --json repository,number,title,updatedAt,url

depois gh pr view <n> --json reviewDecision,reviews,comments,headRefOid por PR para os campos de comparação. Nenhuma credencial para configurar no n8n; a autenticação vai no keyring existente.

Três notas de implementação que evitaram retrabalho real:

• Feche o stdin em comandos de CLI. O node Execute Command mantém stdin aberto por padrão, e CLIs que esperam entrada travam para sempre — a execução fica “running” indefinidamente. Acrescentar </dev/null ao comando é a correção.
• Mantenha os snapshots append-only. Data tables não têm delete de linha nem pelo node nem pelo MCP. Insira linhas só para itens novos ou alterados, e compare contra a última linha por chave. O GitHub nunca reutiliza número de PR, então linha velha não gera falso positivo.
• Notifique só em mudanças. “Nada mudou” é o desfecho mais comum e precisa ficar em silêncio. PR novo, push novo, aprovação, pedido de mudança, delta de comentários, PR fechado — cada um vira uma notificação com o delta no corpo.

A notificação é uma linha no macOS, disparada do mesmo node que roda o diff:

osascript -e 'display notification "delta aqui" with title "PR Monitor" sound name "Glass"'

Notificações de desktop antes do Slack foi proposital: zero setup, e trocar o canal depois é editar um node.

Passo 5: deixar o agente construir — onde a IA ajuda de fato

O monitor em si não precisa de modelo; o diff é mecânico. O agente ganha seu lugar em dois outros pontos.

Montagem pelo MCP. Descreva a automação em uma frase — “acompanhe meus PRs abertos, me avise de reviews, comentários e pushes novos” — e o agente monta pelo MCP: pesquisa os nodes certos, valida o código do Workflow SDK antes de salvar, cria o workflow, liga o agendamento e publica. O meu errou — um node que o MCP recusou, um session ID fixo no código — e cada correção foi conversa, não reescrita de JSON.

Nodes de interpretação. O diff no grafo é a nível de campo. Para um resumo humano — “3 comentários novos, um pedindo mudanças no arquivo de auth” — um Code node chama um agente local headless com o delta. O n8n segue como máquina de estados; o agente vira o leitor.

Manhãs entre sistemas. O mesmo esqueleto puxa stories do Shortcut, alertas do Grafana e atualizações do Notion num brief único diário.

A divisão que se sustentou: o n8n fica com agendamento, estado, retries e entrega. O agente fica com leitura, julgamento e escrita.

O fluxo completo, consolidado

# 1. Instalar (num terminal novo para as env vars carregarem)
npx --yes --registry=https://registry.npmjs.org n8n

# 2. Backup da chave de criptografia imediatamente
cp ~/.n8n/config ~/.n8n/config.backup-$(date +%Y%m%d)

# 3. Na UI: habilitar instance-level MCP, gerar o token MCP
# 4. Exportar para o cliente MCP — evite o prefixo N8N_ no nome
export N8N_MCP_TOKEN="..."

# 5. Apontar o MCP do agente para http://localhost:5678/mcp-server/http
# 6. Criar a data table com o estado anterior/depois do monitor
# 7. Montar o workflow: schedule → coletar → diff → notificar → persistir
# 8. Habilitar MCP access no workflow e publicar

Checklist

• Faça backup de ~/.n8n/config antes de guardar qualquer credencial.
• Não confunda os dois tipos de credencial: token MCP vs public API key.
• Evite o prefixo N8N_ ao nomear suas próprias variáveis de ambiente.
• Feche o stdin (</dev/null) em CLIs dentro de nodes Execute Command.
• Habilite MCP access por workflow; a elegibilidade exige trigger suportado.
• Guarde snapshots append-only e compare contra a última linha por chave.
• Notifique só em mudanças — silêncio é feature.

Estendendo o padrão

Depois que o esqueleto existe — schedule, coletar, diff, julgar, notificar — tudo que muda e importa entra: resumos de alertas do Grafana, movimentação de stories no Shortcut, atualizações no Notion, deploys de release. Se quiser o contexto completo do agente por trás, os posts anteriores cobrem por que migrei para o OMP e como um marketplace pessoal empacota esse setup.