README - n8n-manager-for-ai-agents by czlonkowski

n8n Manager for AI Agents

[!IMPORTANT] This repository is no longer being actively developed. The n8n instance management tools have been integrated into the more comprehensive n8n-mcp project, which provides a complete solution for n8n automation with AI agents.

Please use n8n-mcp for the latest features and updates.

A Model Context Protocol (MCP) server that enables Claude Desktop and other AI agents to manage n8n workflow automation instances through the n8n API.

🎯 Project Overview

This MCP server provides AI agents with tools to manage n8n workflows programmatically. It implements the core n8n API operations with intelligent workarounds for API limitations.

✅ What's Working

Workflow Management: Create, read, update, and delete workflows
Execution Monitoring: List and view execution details, delete execution records
Webhook Triggers: Execute workflows via webhook endpoints
Health Monitoring: Check n8n instance connectivity and configuration

🚧 Current Limitations

Workflow Activation: Cannot activate/deactivate workflows via API (manual UI activation required)
Direct Execution: Not available - must use webhook triggers
Tags & Credentials: Read-only fields, cannot be set via API

🚀 Implemented Features

Workflow Operations: Full CRUD operations for n8n workflows
Execution Management: View, list, and delete execution records
Webhook-Based Execution: Trigger workflows via webhook URLs
Smart Error Handling: Automatic removal of read-only fields, method fallbacks
AI-Friendly Descriptions: Enhanced tool descriptions with examples and clear limitations
Cursor-Based Pagination: Efficient handling of large result sets
Health Monitoring: Built-in connectivity and configuration checks

⚠️ API Limitations & Workarounds

Discovered Limitations

Workflow Activation: The active field is read-only - workflows must be activated manually in the UI
Tags Field: Read-only during creation and updates
PATCH Method: Some n8n instances don't support PATCH for workflow updates
Direct Execution: Must use webhook triggers (no direct execution API)
Settings Field: Required but undocumented - we provide sensible defaults

Not Implemented (API Unavailable)

User Management: No public API endpoints
Credential Management: Limited API, schemas not exposed
Stop Execution: Cannot stop running executions via API
Variables: Only available through source control API
Import/Export: Planned but not yet implemented

📦 Available MCP Tools

Workflow Management

n8n_create_workflow - Create new workflows with nodes and connections
n8n_get_workflow - Retrieve workflow details by ID
n8n_update_workflow - Update existing workflows (requires full node list)
n8n_delete_workflow - Delete workflows permanently
n8n_list_workflows - List workflows with filtering and pagination

Execution Management

n8n_trigger_webhook_workflow - Trigger workflows via webhook URL
n8n_get_execution - Get detailed execution information
n8n_list_executions - List executions with status filtering
n8n_delete_execution - Delete execution records

System Tools

n8n_health_check - Check API connectivity and configuration

🛠️ Technology Stack

Runtime: Node.js 20+
Language: TypeScript 5.0
MCP SDK: @modelcontextprotocol/sdk v1.13.1
HTTP Client: Axios with retry logic
Validation: Zod schemas
Logging: Winston (file-based in MCP mode)
Build: TypeScript with ES modules

📋 Prerequisites

Node.js 20 or higher
n8n instance with API access enabled
n8n API key
Claude Desktop (for MCP integration)

🚀 Quick Start

Clone the repository

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

Install dependencies
```
npm install
```

Configure environment

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

Build the project
```
npm run build
```

Configure Claude Desktop Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on 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"
      }
    }
  }
}

Restart Claude Desktop and verify the n8n-manager appears in the MCP tools list

📁 Log Files

Logs are written to ~/.n8n-manager/logs/n8n-manager.log to avoid interfering with MCP protocol communication.

💡 Usage Examples

Creating a Simple Workflow

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

Listing Workflows

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

Checking Executions

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

Webhook Execution

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

📖 Documentation

- AI guidance, examples, and error solutions
- Original project specifications
- Development progress

🧪 Development

# 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

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

🔐 Security

API keys are stored in environment variables
No sensitive data is logged
All communications use HTTPS
Implements rate limiting and request validation

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

n8n - The workflow automation platform
Anthropic - For Claude and the MCP protocol
Model Context Protocol - The protocol enabling this integration

📞 Contact

Romuald Czlonkowski
aiadvisors.pl

Phase 1 Complete: Core workflow and execution management tools are fully functional. See for detailed usage guidance and common error solutions.