n8n-mcp/README.md

# n8n-mcp

Integration between n8n workflow automation and Model Context Protocol (MCP). This project provides:

- An MCP server that exposes n8n workflows and operations to AI assistants
- A custom n8n node for connecting to MCP servers from within workflows

## Features

- **MCP Server**: Expose n8n workflows as tools, resources, and prompts for AI assistants
- **n8n Node**: Connect to any MCP server from n8n workflows
- **Bidirectional Integration**: Use AI capabilities in n8n and n8n automation in AI contexts
- **Authentication**: Secure token-based authentication
- **Flexible Transport**: Support for WebSocket and stdio connections

## Quick Start

### Prerequisites

- Node.js 18+ 
- n8n instance with API access enabled
- MCP-compatible AI assistant (Claude, etc.)

### Installation

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

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Configure your n8n API credentials
# Edit .env with your n8n instance details
```

### Running the MCP Server

```bash
# Build the project
npm run build

# Start the MCP server
npm start
```

For development:
```bash
npm run dev
```

## Configuration

### Environment Variables

Create a `.env` file based on `.env.example`:

```env
# MCP Server Configuration
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost

# n8n Configuration
N8N_API_URL=http://localhost:5678
N8N_API_KEY=your-n8n-api-key

# Authentication
MCP_AUTH_TOKEN=your-secure-token

# Logging
LOG_LEVEL=info
```

## Usage

### Using the MCP Server with Claude

Add the server to your Claude configuration:

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

### Available MCP Tools

- `execute_workflow` - Execute an n8n workflow by ID
- `list_workflows` - List all available workflows
- `get_workflow` - Get details of a specific workflow
- `create_workflow` - Create a new workflow
- `update_workflow` - Update an existing workflow
- `delete_workflow` - Delete a workflow
- `get_executions` - Get workflow execution history
- `get_execution_data` - Get detailed execution data

### Using the n8n MCP Node

1. Copy the node files to your n8n custom nodes directory
2. Restart n8n
3. The MCP node will appear in the nodes panel
4. Configure with your MCP server credentials
5. Select operations: Call Tool, List Tools, Read Resource, etc.

### Example n8n Workflow

```json
{
  "name": "MCP AI Assistant",
  "nodes": [
    {
      "name": "MCP",
      "type": "mcp",
      "parameters": {
        "operation": "callTool",
        "toolName": "generate_text",
        "toolArguments": "{\"prompt\": \"Write a summary\"}"
      }
    }
  ]
}
```

## Architecture

### Project Structure

```
n8n-mcp/
├── src/
│   ├── mcp/          # MCP server implementation
│   ├── n8n/          # n8n node implementation
│   ├── utils/        # Shared utilities
│   └── types/        # TypeScript type definitions
├── tests/            # Test files
└── dist/             # Compiled output
```

### Key Components

- **MCP Server**: Handles MCP protocol requests and translates to n8n API calls
- **n8n API Client**: Manages communication with n8n instance
- **Bridge Layer**: Converts between n8n and MCP data formats
- **Authentication**: Validates tokens and manages access control

## Development

### Running Tests

```bash
npm test
```

### Building

```bash
npm run build
```

### Type Checking

```bash
npm run typecheck
```

## API Reference

### MCP Tools

#### execute_workflow
Execute an n8n workflow by ID.

Parameters:
- `workflowId` (string, required): The workflow ID
- `data` (object, optional): Input data for the workflow

#### list_workflows
List all available workflows.

Parameters:
- `active` (boolean, optional): Filter by active status
- `tags` (array, optional): Filter by tags

### MCP Resources

- `workflow://active` - List of active workflows
- `workflow://all` - List of all workflows
- `execution://recent` - Recent execution history
- `credentials://types` - Available credential types
- `nodes://available` - Available n8n nodes

### MCP Prompts

- `create_workflow_prompt` - Generate workflow creation prompts
- `debug_workflow_prompt` - Debug workflow issues
- `optimize_workflow_prompt` - Optimize workflow performance
- `explain_workflow_prompt` - Explain workflow functionality

## Troubleshooting

### Common Issues

1. **Connection refused**: Ensure n8n is running and API is enabled
2. **Authentication failed**: Check your API key in .env
3. **Workflow not found**: Verify workflow ID exists in n8n
4. **MCP connection failed**: Check server is running and accessible

### Debug Mode

Enable debug logging:
```env
LOG_LEVEL=debug
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

ISC License - see LICENSE file for details

## Support

- Issues: https://github.com/czlonkowski/n8n-mcp/issues
- n8n Documentation: https://docs.n8n.io
- MCP Specification: https://modelcontextprotocol.io