# n8n MCP Server

Model Context Protocol (MCP) server for n8n workflow automation platform. This server provides AI models with comprehensive access to n8n workflows through a standardized MCP interface.

## Quick Start

### Prerequisites

- n8n instance running (local or remote)
- n8n API key ([how to get API key](https://docs.n8n.io/api/authentication/))
- Node.js 22.10.0 or higher

### Installation

Install and run directly using npx (no local clone required):

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

### Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

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

After saving, restart Claude Desktop. You can now ask Claude to manage your n8n workflows!

**Example prompts**:
- "List all my n8n workflows"
- "Create a new workflow called 'Email Automation'"
- "Show me the details of workflow ID abc123"
- "Update workflow xyz456 to add a new node"

## Features

- **Complete Workflow Management**: Create, read, update, and delete n8n workflows
- **Optimized Responses**: Context-efficient data structures for AI model consumption
- **Flexible Authentication**: API key-based authentication
- **Dual Transport Support**: stdio and HTTP transports
- **Comprehensive Error Handling**: Structured error responses with meaningful messages

## Configuration

### CLI Options

```bash
# Basic usage (uses environment variables)
npx @r_masseater/n8n-mcp-server

# With CLI options
npx @r_masseater/n8n-mcp-server --n8n-url http://localhost:5678 --api-key your-key --log-level debug

# HTTP transport (for development/testing)
npx @r_masseater/n8n-mcp-server --transport http --port 3000
```

### Environment Variables

Alternatively, you can use environment variables:

```bash
# Required
export N8N_URL="http://localhost:5678"          # n8n instance URL
export N8N_API_KEY="your-api-key"              # n8n API key

# Optional
export LOG_LEVEL="info"                         # Log level (error|warn|info|debug)
```

## Development

If you want to develop or contribute to this project:

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

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run in development mode with auto-reload
pnpm run dev

# Run tests
pnpm test
```

## Available MCP Tools

### 1. `list_workflows`

List n8n workflows with optional filtering.

**Parameters:**
- `active` (boolean, optional): Filter by active status
- `tags` (array of strings, optional): Filter by tags
- `limit` (number, optional): Maximum number of workflows to return (1-100)
- `offset` (number, optional): Number of workflows to skip

**Example:**
```json
{
  "name": "list_workflows",
  "arguments": {
    "active": true,
    "tags": ["automation", "production"],
    "limit": 10
  }
}
```

### 2. `get_workflow`

Get detailed information about a specific workflow.

**Parameters:**
- `id` (string, required): Workflow ID

**Example:**
```json
{
  "name": "get_workflow",
  "arguments": {
    "id": "workflow-123"
  }
}
```

### 3. `create_workflow`

Create a new workflow.

**Parameters:**
- `name` (string, required): Workflow name
- `nodes` (array, optional): Workflow nodes
- `connections` (object, optional): Node connections
- `active` (boolean, optional): Whether workflow is active
- `tags` (array of strings, optional): Workflow tags

**Example:**
```json
{
  "name": "create_workflow",
  "arguments": {
    "name": "My New Workflow",
    "nodes": [
      {
        "id": "node1",
        "type": "n8n-nodes-base.start",
        "position": [100, 100]
      }
    ],
    "connections": {},
    "active": false,
    "tags": ["automation"]
  }
}
```

### 4. `update_workflow`

Update an existing workflow.

**Parameters:**
- `id` (string, required): Workflow ID
- `name` (string, optional): New workflow name
- `nodes` (array, optional): Updated workflow nodes
- `connections` (object, optional): Updated node connections
- `active` (boolean, optional): Updated active status
- `tags` (array of strings, optional): Updated workflow tags

**Example:**
```json
{
  "name": "update_workflow",
  "arguments": {
    "id": "workflow-123",
    "name": "Updated Workflow Name",
    "active": true,
    "tags": ["updated", "production"]
  }
}
```

### 5. `delete_workflow`

Delete a workflow.

**Parameters:**
- `id` (string, required): Workflow ID

**Example:**
```json
{
  "name": "delete_workflow",
  "arguments": {
    "id": "workflow-123"
  }
}
```


## Usage Examples

### Using with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/path/to/n8n-mcp-server/dist/index.js"],
      "env": {
        "N8N_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

### Using with other MCP clients

The server supports both stdio and HTTP transports:

```bash
# stdio transport (default)
pnpm start

# HTTP transport
pnpm start --transport http --port 3000
```

## Development

### Project Structure

```
src/
├── clients/           # n8n API client implementations
├── config/           # Configuration management
├── interfaces/       # TypeScript interfaces
├── optimizers/      # Response optimization
├── server/          # MCP server implementation
├── types/           # Type definitions
└── index.ts         # Main entry point
```

### Scripts

```bash
# Development
pnpm run dev          # Start in development mode
pnpm run build        # Build the project
pnpm run type-check   # TypeScript type checking

# Production
pnpm start            # Start the server
pnpm start:stdio      # Start with stdio transport
pnpm start:http      # Start with HTTP transport
```

### Testing

```bash
# Run type checking
pnpm run type-check

# Build and test
pnpm run build
```

## Error Handling

The server provides structured error responses:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: Failed to authenticate with n8n API"
    }
  ],
  "isError": true
}
```

Common error scenarios:
- **Authentication failures**: Invalid API key or n8n instance unreachable
- **Workflow not found**: Invalid workflow ID
- **Validation errors**: Invalid parameters or workflow structure
- **Network errors**: Connection timeouts or API unavailability

## Response Optimization

The server optimizes responses for AI model consumption:

- **Minimized context**: Removes unnecessary fields and metadata
- **Essential information**: Preserves critical workflow data
- **Pagination support**: Handles large datasets efficiently
- **Structured format**: Consistent JSON responses

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run type checking and build
5. Submit a pull request

## License

MIT License - see LICENSE file for details.