n8n Manager for AI Agents MCP Server

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

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Configure environment

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

4. Build the project

   npm run build
   

5. Configure Claude Desktop Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "n8n-manager": {
         "comma