npm package: @myflowsjs/n8n-mcp-server
Description: 🚧 [DEVELOPMENT] MCP server for n8n workflow management - Work in Progress
Author: Tiger Zhang
Latest version: 0.8.0

# n8n MCP Server

A comprehensive Model Context Protocol (MCP) server for n8n workflow automation. This server enables AI assistants to fully manage n8n workflows, monitor executions, and access a complete node knowledge base through the MCP protocol.

## 🚀 Features

### ✅ Complete Workflow Management
- **Create & Update** - Build workflows programmatically with full node configuration
- **Activate & Deactivate** - Control workflow execution state
- **Delete** - Clean up workflows when no longer needed
- **List & Filter** - Find workflows by status, tags, name, or project
- **Smart Updates** - Partial or complete workflow updates with automatic merging

### ✅ Execution Monitoring & Control
- **List Executions** - Query execution history with filtering and pagination
- **Execution Details** - Get detailed execution information with duration analysis
- **Retry Failed Executions** - Automatically retry with optional workflow reload
- **Delete Executions** - Clean up execution history
- **Statistics** - Automatic success rate and status distribution calculation

### ✅ Enhanced Node Knowledge Base (456 nodes)
- **Complete n8n node catalog** with parameter examples from real workflows
- **Usage Statistics** - See which nodes are most commonly used
- **Parameter Examples** - Real-world parameter configurations
- **Smart Search** - Find nodes by name, category, or functionality
- **AI Agent Support** - Full support for AI/LangChain nodes

### ✅ Production Ready
- **TypeScript** - Full type safety and modern development experience
- **Comprehensive Error Handling** - Clear error messages and logging
- **API Validation** - All methods verified against n8n API v1.1.1
- **Extensive Testing** - Test suites for all major features
- **CLI Support** - Works with npx or global installation

## 🛠️ Available Tools (20+)

### Workflow Management
- `n8n_list_workflows` - List and filter workflows
- `n8n_get_workflow` - Get workflow details
- `n8n_create_workflow` - Create new workflows
- `n8n_update_workflow` - Update existing workflows
- `n8n_activate_workflow` - Activate workflows
- `n8n_deactivate_workflow` - Deactivate workflows
- `n8n_delete_workflow` - Delete workflows

### Execution Management
- `n8n_list_executions` - Query execution history
- `n8n_get_execution` - Get execution details
- `n8n_retry_execution` - Retry failed executions
- `n8n_delete_execution` - Delete execution records

### Node Discovery
- `search_n8n_nodes` - Search nodes by name or category
- `get_n8n_node_details` - Get detailed node information with usage examples
- `list_n8n_categories` - Browse all node categories
- `get_popular_n8n_nodes` - Discover most commonly used nodes (based on real usage)
- `get_n8n_tool_nodes` - Find AI-compatible nodes
- `get_n8n_stats` - Get comprehensive node statistics

### System Tools
- `echo` - Test MCP connectivity
- `n8n_health_check` - Verify n8n instance connectivity

## 📚 Available Resources

- `n8n://server-info` - Server and connection information
- `n8n://nodes/search` - Node search with query parameters
- `n8n://nodes/{nodeName}` - Specific node details
- `n8n://categories` - All node categories
- `n8n://categories/{category}` - Nodes in specific category
- `n8n://stats` - Node knowledge base statistics
- `n8n://nodes/popular` - Popular node list (based on real usage)
- `n8n://nodes/tools` - AI-compatible nodes

## 📊 Data Sources

- **Node Definitions**: 456 nodes from n8n source code
- **Parameter Examples**: Real configurations from 57 production workflows
- **Usage Statistics**: Actual usage data showing most popular nodes
- **Node Schemas**: Complete parameter schemas for validation

Top 5 most used nodes:
1. `set` (36 uses) - Data manipulation
2. `agent` (23 uses) - AI Agent
3. `respondToWebhook` (23 uses) - Webhook responses
4. `webhook` (19 uses) - Webhook triggers
5. `lmChatOllama` (16 uses) - Ollama LLM

## Installation

### Global Installation

```bash
npm install -g n8n-mcp-server
```

### Using npx

```bash
npx n8n-mcp-server --n8n-url http://localhost:5678 --api-key your-api-key
```

## Configuration

The server can be configured using environment variables or command line arguments:

### Environment Variables

```bash
export N8N_URL=http://localhost:5678
export N8N_API_KEY=your-api-key
```

### Command Line Arguments

```bash
n8n-mcp-server --n8n-url http://localhost:5678 --api-key your-api-key
```

## Usage

### MCP Client Configuration

Add to your MCP client configuration (e.g., Kiro IDE):

```json
{
  "mcpServers": {
    "n8n-mcp-server": {
      "command": "npx",
      "args": ["@myflowsjs/n8n-mcp-server"],
      "env": {
        "N8N_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Example Usage

Once configured, you can use the tools in your AI assistant:

#### Node Discovery
```javascript
// Search for HTTP-related nodes
search_n8n_nodes({ query: "http", limit: 5 })

// Get details about a specific node with usage examples
get_n8n_node_details({ nodeName: "set" })

// Get most popular nodes based on real usage
get_popular_n8n_nodes({ limit: 10 })
```

#### Workflow Management
```javascript
// List all workflows
n8n_list_workflows({ limit: 10 })

// Create a new workflow
n8n_create_workflow({
  name: "My Workflow",
  nodes: [...],
  connections: {...}
})

// Update a workflow
n8n_update_workflow({
  id: "workflow-id",
  name: "Updated Name"
})

// Activate a workflow
n8n_activate_workflow({ id: "workflow-id" })

// Delete a workflow
n8n_delete_workflow({ id: "workflow-id" })
```

#### Execution Monitoring
```javascript
// List recent executions
n8n_list_executions({ limit: 20 })

// Filter by status
n8n_list_executions({ status: "error", limit: 10 })

// Get execution details
n8n_get_execution({ id: 12345 })

// Retry a failed execution
n8n_retry_execution({ id: 12345, loadWorkflow: true })

// Delete an execution
n8n_delete_execution({ id: 12345 })

# Check server statistics
get_n8n_stats()
```

### Resource Access

You can also access information via resources:

- Browse categories: `n8n://categories`
- Search nodes: `n8n://nodes/search?q=email&category=Communication`
- Get node details: `n8n://nodes/httpRequest`
- View statistics: `n8n://stats`

## 📦 Data Files

This package includes pre-extracted data files that are bundled with the published package:

### Included Data
- **Node Information** (`nodes.json`) - 529 nodes with descriptions, categories, and metadata
- **Parameter Examples** (`node-parameter-examples.json`) - Real-world parameter usage from 57 workflows

### No External Dependencies
- ✅ All data is pre-extracted and included in the package
- ✅ No need for n8n source code
- ✅ No need to run extraction scripts
- ✅ Fast startup with internal data storage

### For Developers
If you want to update the data files, see [DATA-EXTRACTION.md](./DATA-EXTRACTION.md) for details on:
- How to extract node parameter examples from your n8n instance
- How to update node information
- Data file formats and update strategies

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- Access to an n8n instance with API enabled

### Setup

```bash
# Clone the repository
git clone https://github.com/myflows-platform/n8n-mcp-server-v2.git
cd n8n-mcp-server-v2/n8n-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev
```

### Scripts

- `npm run build`: Compile TypeScript to JavaScript
- `npm run dev`: Watch mode for development
- `npm run start`: Start the compiled server
- `npm run lint`: Run ESLint
- `npm run lint:fix`: Fix ESLint issues automatically
- `npm run clean`: Remove build artifacts

### Testing

To test the MCP server functionality:

```bash
# Build the project
npm run build

# Run the MCP test script
node test-mcp.js
```

The test script verifies:
- MCP protocol initialization
- Tool listing and execution
- Resource listing and reading
- Error handling
- n8n connectivity checking

See `test-results.md` for detailed test results.

## License

MIT