n8n Manager for AI Agents

Gerencie instâncias de automação de fluxo de trabalho n8n através de linguagem natural usando a API pública do n8n.

Documentação

n8n Manager for AI Agents

[!IMPORTANT] Este repositório não está mais em desenvolvimento ativo. As ferramentas de gerenciamento de instâncias n8n foram integradas ao projeto mais abrangente n8n-mcp, que fornece uma solução completa para automação n8n com agentes de IA.

Por favor, use n8n-mcp para os recursos e atualizações mais recentes.

Um servidor Model Context Protocol (MCP) que permite ao Claude Desktop e outros agentes de IA gerenciar instâncias de automação de fluxos de trabalho n8n através da API do n8n.

🎯 Visão Geral do Projeto

Este servidor MCP fornece aos agentes de IA ferramentas para gerenciar fluxos de trabalho n8n programaticamente. Ele implementa as operações principais da API do n8n com soluções inteligentes para limitações da API.

✅ O Que Está Funcionando

Gerenciamento de Fluxos de Trabalho: Criar, ler, atualizar e excluir fluxos de trabalho
Monitoramento de Execuções: Listar e visualizar detalhes de execuções, excluir registros de execução
Gatilhos de Webhook: Executar fluxos de trabalho via endpoints de webhook
Monitoramento de Saúde: Verificar conectividade e configuração da instância n8n

🚧 Limitações Atuais

Ativação de Fluxos de Trabalho: Não é possível ativar/desativar fluxos de trabalho via API (ativação manual pela interface necessária)
Execução Direta: Não disponível - deve-se usar gatilhos de webhook
Tags e Credenciais: Campos somente leitura, não podem ser definidos via API

🚀 Recursos Implementados

Operações de Fluxo de Trabalho: Operações CRUD completas para fluxos de trabalho n8n
Gerenciamento de Execuções: Visualizar, listar e excluir registros de execução
Execução Baseada em Webhook: Acionar fluxos de trabalho via URLs de webhook
Tratamento Inteligente de Erros: Remoção automática de campos somente leitura, fallbacks de métodos
Descrições Amigáveis para IA: Descrições aprimoradas de ferramentas com exemplos e limitações claras
Paginação Baseada em Cursor: Manipulação eficiente de grandes conjuntos de resultados
Monitoramento de Saúde: Verificações integradas de conectividade e configuração

⚠️ Limitações da API e Soluções

Limitações Descobertas

Ativação de Fluxos de Trabalho: O campo active é somente leitura - os fluxos de trabalho devem ser ativados manualmente na interface
Campo de Tags: Somente leitura durante criação e atualizações
Método PATCH: Algumas instâncias n8n não suportam PATCH para atualizações de fluxos de trabalho
Execução Direta: Deve-se usar gatilhos de webhook (sem API de execução direta)
Campo de Configurações: Obrigatório, mas não documentado - fornecemos padrões sensatos

Não Implementado (API Indisponível)

Gerenciamento de Usuários: Sem endpoints públicos de API
Gerenciamento de Credenciais: API limitada, schemas não expostos
Parar Execução: Não é possível parar execuções em andamento via API
Variáveis: Disponível apenas através da API de controle de versão
Importação/Exportação: Planejado, mas ainda não implementado

📦 Ferramentas MCP Disponíveis

Gerenciamento de Fluxos de Trabalho

n8n_create_workflow - Criar novos fluxos de trabalho com nós e conexões
n8n_get_workflow - Recuperar detalhes do fluxo de trabalho por ID
n8n_update_workflow - Atualizar fluxos de trabalho existentes (requer lista completa de nós)
n8n_delete_workflow - Excluir fluxos de trabalho permanentemente
n8n_list_workflows - Listar fluxos de trabalho com filtragem e paginação

Gerenciamento de Execuções

n8n_trigger_webhook_workflow - Acionar fluxos de trabalho via URL de webhook
n8n_get_execution - Obter informações detalhadas de execução
n8n_list_executions - Listar execuções com filtragem por status
n8n_delete_execution - Excluir registros de execução

Ferramentas do Sistema

n8n_health_check - Verificar conectividade e configuração da API

🛠️ Stack de Tecnologia

Runtime: Node.js 20+
Linguagem: TypeScript 5.0
SDK MCP: @modelcontextprotocol/sdk v1.13.1
Cliente HTTP: Axios com lógica de retry
Validação: Schemas Zod
Registro de Logs: Winston (baseado em arquivo no modo MCP)
Build: TypeScript com módulos ES

📋 Pré-requisitos

Node.js 20 ou superior
Instância n8n com acesso à API habilitado
Chave de API do n8n
Claude Desktop (para integração MCP)

🚀 Início Rápido

Clonar o repositório

git clone https://github.com/czlonkowski/n8n-manager-for-ai-agents
cd n8n-manager-for-ai-agents

Instalar dependências
```
npm install
```

Configurar ambiente

cp .env.example .env
# Edit .env with your n8n instance details

Compilar o projeto
```
npm run build
```

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

{
  "mcpServers": {
    "n8n-manager": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-manager-for-ai-agents/build/index.js"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production",
        "MCP_MODE": "stdio"
      }
    }
  }
}

Reiniciar o Claude Desktop e verificar se o n8n-manager aparece na lista de ferramentas MCP

📁 Arquivos de Log

Os logs são gravados em ~/.n8n-manager/logs/n8n-manager.log para evitar interferência na comunicação do protocolo MCP.

💡 Exemplos de Uso

Criando um Fluxo de Trabalho Simples

"Create a workflow named 'Test API' with a manual trigger"

Listando Fluxos de Trabalho

"Show me all active workflows"
"List workflows with tag 'production'"

Verificando Execuções

"Show recent executions for workflow ID abc123"
"Get details of execution xyz789"

Execução via Webhook

"Trigger the webhook at https://n8n.example.com/webhook/abc-def-ghi"

📖 Documentação

CLAUDE.md - Orientação para IA, exemplos e soluções de erros
Documento de Requisitos do Produto - Especificações originais do projeto
Checklist de Implementação - Progresso do desenvolvimento

🧪 Desenvolvimento

# Run tests
npm test

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Build for production
npm run build

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, abra uma issue primeiro para discutir o que você gostaria de alterar.

🔐 Segurança

Chaves de API são armazenadas em variáveis de ambiente
Nenhum dado sensível é registrado em logs
Todas as comunicações usam HTTPS
Implementa limitação de taxa e validação de requisições

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

n8n - A plataforma de automação de fluxos de trabalho
Anthropic - Pelo Claude e o protocolo MCP
Model Context Protocol - O protocolo que possibilita esta integração

📞 Contato

Romuald Czlonkowski
aiadvisors.pl

Fase 1 Concluída: As ferramentas principais de gerenciamento de fluxos de trabalho e execuções estão totalmente funcionais. Consulte CLAUDE.md para orientações detalhadas de uso e soluções comuns de erros.