# n8n MCP Server

A Model Context Protocol (MCP) server that wraps the **n8n self-hosted REST API**, letting Claude (and any MCP-compatible LLM client) manage your n8n instance through natural language.

## Features

30+ tools covering:

| Domain | Operations |
|--------|-----------|
| **Workflows** | list, get, create, update, delete, activate, deactivate, archive, unarchive, manage tags |
| **Executions** | list, get, delete, retry, stop |
| **Credentials** | list, get, get schema, create, update, delete, test |
| **Tags** | list, create, update, delete |
| **Variables** | list, create, update, delete |
| **Projects** | list, create |
| **Users** | list |
| **System** | security audit, discover API capabilities, manage community packages |

## Prerequisites

- Node.js 18+
- A self-hosted n8n instance (v1.0+)
- An n8n REST API key (see [Getting an API Key](#getting-an-api-key))

## Getting an API Key

1. Open your n8n instance
2. Go to **Settings → n8n API**
3. Click **Create an API key**
4. Copy the generated key — you will not be able to see it again

> The API key inherits the permissions of the user who created it. Use an **owner** account to unlock all tools (credential listing, user management, audit).

## Installation

```bash
git clone https://git.verzth.work/mcp/n8n.git
cd n8n
npm install
npm run build
```

## Configuration

### Claude Desktop

Add the following entry 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": "node",
      "args": ["/absolute/path/to/n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.example.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Replace `/absolute/path/to/n8n` with the actual directory where you cloned the repo.

### Claude Code (CLI)

Add to your project's `.claude/settings.json` or global `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.example.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `N8N_BASE_URL` | ✅ | Base URL of your n8n instance (e.g. `https://n8n.example.com`) |
| `N8N_API_KEY` | ✅ | API key from n8n Settings → n8n API |

## Usage Examples

Once configured, you can ask Claude things like:

```
List all active workflows in n8n
```
```
Show me the last 10 failed executions
```
```
Activate the workflow named "Daily Report"
```
```
Create a new tag called "production" and apply it to workflow abc123
```
```
Test the Slack credential
```
```
Run a security audit on my n8n instance
```
```
What community packages do I have installed?
```

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild on change)
npm run dev
```

## Project Structure

```
src/
├── index.ts              # Entry point — server init + transport
├── types.ts              # TypeScript interfaces
├── constants.ts          # Shared constants (limits, pagination)
├── services/
│   └── n8n-client.ts     # Axios client + error handler
└── tools/
    ├── workflows.ts      # Workflow management tools
    ├── executions.ts     # Execution management tools
    ├── credentials.ts    # Credential management tools
    ├── tags.ts           # Tag management tools
    ├── variables.ts      # Variable management tools
    └── misc.ts           # Projects, users, audit, packages
```

## Transport

This server uses **stdio** transport, which means it runs as a subprocess of the MCP client. It does not expose any network ports and all authentication credentials are passed via environment variables — they never touch the codebase.

## Security Notes

- API keys are read from environment variables only — never hardcode them
- The server only talks to the n8n instance you configure
- Destructive tools (`delete`, `uninstall`) are annotated with `destructiveHint: true` so clients can prompt for confirmation
- Credential secret data is intentionally excluded from `n8n_list_credentials` and `n8n_get_credential` responses (n8n API design — secrets are write-only)

## License

MIT