Chatwoot MCP Server

Model Context Protocol (MCP) server for Chatwoot API integration. Enables AI assistants to manage customer conversations, messages, and contacts in Chatwoot.

Features

• Conversations Management: List, filter, and retrieve conversation details
• Message Operations: Read message history and send new messages
• Type-Safe: Built with TypeScript using OpenAPI-generated types
• Flexible Auth: Supports both API token (recommended) and JWT authentication

Tools Provided

Conversations

• chatwoot_list_conversations - List conversations with filtering (status, assignee, inbox)
• chatwoot_get_conversation - Get detailed info for a specific conversation

Messages

• chatwoot_list_messages - List all messages in a conversation
• chatwoot_create_message - Send a message or create an internal note

Installation

Via npm (recommended)

npx chatwoot-mcp-server

Or install globally:

npm install -g chatwoot-mcp-server
chatwoot-mcp-server

From source

git clone https://github.com/hugoblanc/chatwoot-mcp.git
cd chatwoot-mcp
npm install
npm run build

Configuration

Recommended: API Access Token

The simplest method using your Chatwoot API token (no expiration).

Get your API token:

1. Log in to your Chatwoot account
2. Click your avatar → Profile Settings
3. Scroll to bottom → Copy your “Access Token”

Configure .env:

CHATWOOT_BASE_URL="https://your-chatwoot-instance.com"
CHATWOOT_API_TOKEN="your_api_token_here"

Alternative: JWT Authentication

Use email/password if API tokens don’t work on your instance (requires password for token refresh).

CHATWOOT_BASE_URL="https://your-chatwoot-instance.com"
CHATWOOT_EMAIL="[email protected]"
CHATWOOT_PASSWORD="your_password"

Note: JWT tokens expire and require the password for auto-refresh.

Important for Self-Hosted Instances

If using nginx as reverse proxy (e.g., CapRover), add this to nginx config to support API tokens:

server {
    ...
    underscores_in_headers on;  # Required for api_access_token header
    ...
}

Usage

Using with Claude Code

claude mcp add chatwoot \
  -e CHATWOOT_BASE_URL="https://your-instance.com" \
  -e CHATWOOT_API_TOKEN="your_token" \
  -- npx chatwoot-mcp-server

Using with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chatwoot": {
      "command": "npx",
      "args": ["chatwoot-mcp-server"],
      "env": {
        "CHATWOOT_BASE_URL": "https://your-chatwoot-instance.com",
        "CHATWOOT_API_TOKEN": "your_api_token"
      }
    }
  }
}

Development Mode (from source)

npm run dev

Example Queries

Once connected, you can ask Claude things like:

• “Show me all open conversations in account 3”
• “What are the details of conversation #123?”
• “List all messages in conversation #456”