Metadata-Version: 2.4
Name: n8n-chatbot-mcp
Version: 2.0.0
Summary: Generic n8n Chat Trigger MCP server - any n8n chatbot as an MCP tool
Author: mytsx
License: MIT
Project-URL: Homepage, https://github.com/mytsx/mcp-servers
Project-URL: Repository, https://github.com/mytsx/mcp-servers
Project-URL: Issues, https://github.com/mytsx/mcp-servers/issues
Keywords: mcp,model-context-protocol,chatbot,n8n,webhook
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<3,>=2.2
Requires-Dist: httpx2>=2.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# n8n Chatbot MCP Server

[![Python](https://img.shields.io/badge/python-3.10+-blue?logo=python&logoColor=white)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-2026--07--28-purple)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/n8n-chatbot-mcp)](https://pypi.org/project/n8n-chatbot-mcp/)

Turn any [n8n](https://n8n.io) Chat Trigger webhook into an MCP tool. Just provide the webhook URL — the server auto-discovers the chatbot name, description, welcome message, and required headers from the n8n Chat Trigger page.

## Features

- **Zero Config** — Only the webhook URL is required, everything else is auto-discovered
- **Auto-Discovery** — Extracts name, description, welcome message, and `X-Instance-Id` from the chat UI
- **Multi-Turn** — Session ID support for contextual conversations
- **Multiple Bots** — Register as many n8n chatbots as you want, each as a separate MCP server
- **Additive Description** — Auto-discovered subtitle + optional extra context via env var
- **Structured Output** — Answers come back as typed JSON (`answer`, `session_id`), not loose text
- **Config Resource** — `n8n://config` exposes what auto-discovery found, for inspection and debugging

## Quick Start

### Claude Code

```bash
claude mcp add my-chatbot \
  -e N8N_CHATBOT_URL="https://n8n.example.com/webhook/my-bot/chat" \
  -- uvx n8n-chatbot-mcp
```

### Claude Desktop

Add to your config file:

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

```json
{
  "mcpServers": {
    "my-chatbot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "my-chatbot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### Windsurf

Add to Windsurf MCP config:

```json
{
  "mcpServers": {
    "my-chatbot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### VS Code

Add to your VS Code settings (JSON):

```json
"mcp": {
  "servers": {
    "my-chatbot": {
      "type": "stdio",
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "my-chatbot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### GitHub Copilot

Add to `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "my-chatbot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/my-bot/chat"
      }
    }
  }
}
```

### OpenAI Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.my-chatbot]
command = "uvx"
args = ["n8n-chatbot-mcp"]

[mcp_servers.my-chatbot.env]
N8N_CHATBOT_URL = "https://n8n.example.com/webhook/my-bot/chat"
```

### Install from Source

```bash
cd n8n-chatbot-mcp
pip install -e .
```

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `N8N_CHATBOT_URL` | Yes | — | Full n8n Chat Trigger webhook URL |
| `N8N_CHATBOT_DESCRIPTION` | No | — | Extra context **appended** to auto-discovered description |
| `N8N_CHATBOT_TIMEOUT` | No | `120` | Request timeout in seconds |
| `N8N_CHATBOT_VERIFY_TLS` | No | `true` | Set to `false` only for an n8n behind a self-signed certificate |

TLS certificate verification is **on by default**. If your n8n uses a self-signed
certificate the tool fails with an error naming `N8N_CHATBOT_VERIFY_TLS`; set it to `false`
only when you also trust the network between you and that host.

### Auto-Discovery

At startup the server makes a single GET request to the webhook URL and parses the n8n Chat Trigger HTML to extract:

- **Chatbot name** (from `i18n.title`) — used as the MCP server name
- **Chatbot description** (from `i18n.subtitle`) — used in the tool description
- **Welcome message** (from `initialMessages`) — included in tool context
- **X-Instance-Id header** — sent with every POST request

`N8N_CHATBOT_DESCRIPTION` is **additive**: the auto-discovered subtitle is always included, and the env var value is appended after it.

## Multiple Chatbots

Register as many n8n chatbots as you need — each one is a separate MCP server entry:

```json
{
  "mcpServers": {
    "hr-bot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/hr-bot/chat"
      }
    },
    "it-bot": {
      "command": "uvx",
      "args": ["n8n-chatbot-mcp"],
      "env": {
        "N8N_CHATBOT_URL": "https://n8n.example.com/webhook/it-bot/chat",
        "N8N_CHATBOT_DESCRIPTION": "Also helps with VPN and system access issues"
      }
    }
  }
}
```

## Tool

<details>
<summary><code>ask_chatbot</code> — Send a question to the chatbot</summary>

Sends a question to the n8n chatbot and returns the response.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | Yes | The question to ask |
| `session_id` | string | No | Session ID for multi-turn conversations (auto-generated if omitted) |

Returns structured output:

| Field | Type | Description |
|-------|------|-------------|
| `answer` | string | The chatbot's answer |
| `session_id` | string | Session this answer belongs to — pass it back to continue the conversation |

</details>

## Resource

<details>
<summary><code>n8n://config</code> — Auto-discovered chatbot configuration</summary>

JSON document with the webhook URL, discovered name and description, welcome messages, the
names of the request headers being sent, and the configured timeout. Useful when auto-discovery
does not pick up what you expected.

</details>

## Requirements

Python 3.10+ and MCP SDK 2.x (`mcp>=2.2,<3`). The server speaks the 2026-07-28 protocol
revision and still serves older MCP clients from the same process.

## License

MIT
