# n8n MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with n8n workflow automation platform. This server enables you to manage workflows, executions, and monitor your n8n instance through MCP-compatible clients.

## Features

### Workflow Management
- **`list_workflows`** - Get all workflows with their status and metadata
- **`get_workflow`** - Retrieve detailed information about a specific workflow
- **`activate_workflow`** - Activate a workflow to start automatic execution
- **`deactivate_workflow`** - Deactivate a workflow to stop automatic execution
- **`execute_workflow`** - Manually trigger a workflow execution

### Execution Monitoring
- **`list_executions`** - Get recent workflow executions with optional filtering
- **`get_execution`** - Get detailed information about a specific execution
- **`stop_execution`** - Stop a currently running execution

### Instance Information
- **`get_instance_info`** - Get n8n instance information and health status

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd n8n-thg-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set the following environment variables:

```bash
N8N_API_KEY=your_n8n_api_key_here
N8N_BASE_URL=https://your-n8n-instance.com
```

### Getting n8n API Key

1. Log into your n8n instance
2. Go to Settings → API Keys
3. Create a new API key
4. Copy the generated key

## MCP Server Setup

Add the server to your MCP client configuration:

### For Cline (VSCode Extension)

Add to your MCP settings file (`cline_mcp_settings.json`):

```json
{
  "mcpServers": {
    "n8n-thg-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/n8n-thg-server/build/index.js"],
      "env": {
        "N8N_API_KEY": "your_api_key_here",
        "N8N_BASE_URL": "https://your-n8n-instance.com"
      },
      "autoApprove": []
    }
  }
}
```

### For Claude Desktop

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "n8n-thg-server": {
      "command": "node",
      "args": ["/path/to/n8n-thg-server/build/index.js"],
      "env": {
        "N8N_API_KEY": "your_api_key_here",
        "N8N_BASE_URL": "https://your-n8n-instance.com"
      }
    }
  }
}
```

## Usage Examples

Once the MCP server is configured, you can use it through your MCP client:

- "Show me all my n8n workflows"
- "List recent workflow executions"
- "Execute workflow with ID 123"
- "Get details for execution 456"
- "Activate workflow 789"
- "Show me failed executions from today"

## Development

### Project Structure

```
n8n-thg-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

### Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Watch mode for development
- `npm start` - Run the compiled server

### Building

```bash
npm run build
```

This compiles the TypeScript source to JavaScript in the `build/` directory.

## Authentication Notes

### Cloudflare Access Protected Instances

If your n8n instance is protected by Cloudflare Access (common in enterprise setups), you may need additional configuration:

1. Ensure your API key has proper permissions
2. Configure service account authentication if available
3. Contact your system administrator for API access configuration

The server includes SSL certificate handling for self-signed certificates commonly used in enterprise environments.

## Troubleshooting

### Common Issues

1. **Connection Errors**: Verify your `N8N_BASE_URL` and `N8N_API_KEY`
2. **SSL Certificate Issues**: The server automatically handles self-signed certificates
3. **Authentication Errors**: Check if your n8n instance requires additional authentication steps

### Debug Mode

Set environment variable for detailed logging:
```bash
DEBUG=true node build/index.js
```

## Contributing

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

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Check the troubleshooting section above
- Review n8n API documentation
- Open an issue in this repository