Chatwoot MCP Server

A Model Context Protocol (MCP) server that connects AI assistants like Claude to your Chatwoot instance. Manage customer conversations, read messages, send replies, and filter by date ranges -- all through natural language.

Features

• 5 MCP Tools - List, filter, and inspect conversations; read and send messages

• Advanced Filtering - Filter conversations by date range, status, assignee, inbox, and labels

• Dual Authentication - API token (recommended) or JWT email/password

• Type-Safe - Built with TypeScript and OpenAPI-generated types

• Dual Output - Markdown (human-readable) and JSON (machine-readable) response formats

Related MCP server: aws-mcp

Tools

Quick Start

Prerequisites

• Node.js >= 18

• A Chatwoot account with API access

Install

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

Configure

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env:

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

Getting your API token:

1. Log in to Chatwoot

2. Click your avatar → Profile Settings

3. Scroll to the bottom → copy your Access Token

Getting your account ID: Your account ID is the number in the URL when you're logged in: app.chatwoot.com/app/accounts/<ID>/...

Run

npm start

MCP Configuration

Claude Code

claude mcp add chatwoot \
  -e CHATWOOT_BASE_URL="https://your-chatwoot-instance.com" \
  -e CHATWOOT_API_TOKEN="your_api_token" \
  -e CHATWOOT_ACCOUNT_ID="your_account_id" \
  -- node /path/to/chatwoot-mcp/dist/index.js

Replace /path/to/chatwoot-mcp with the actual path where you cloned the repository.

Claude Desktop

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chatwoot": {
      "command": "node",
      "args": ["/path/to/chatwoot-mcp/dist/index.js"],
      "env": {
        "CHATWOOT_BASE_URL": "https://your-chatwoot-instance.com",
        "CHATWOOT_API_TOKEN": "your_api_token_here",
        "CHATWOOT_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}

Replace /path/to/chatwoot-mcp with the actual path where you cloned the repository. On Windows, use double backslashes: "C:\\Users\\you\\chatwoot-mcp\\dist\\index.js"

Environment Variables

*Either CHATWOOT_API_TOKEN or CHATWOOT_EMAIL is required.

Tools Reference

chatwoot_list_conversations

List conversations from an account with optional filters.

chatwoot_get_conversation

Get detailed information about a specific conversation.

chatwoot_list_messages

List all messages in a conversation.

chatwoot_create_message

Send a message or create an internal note in a conversation.

chatwoot_filter_conversations

Filter conversations using advanced criteria. Uses Chatwoot's POST filter API with support for date ranges, status, assignee, inbox, and labels. Returns 25 results per page.

Date filter behavior: Date boundaries are exclusive. To get conversations for a single day like Feb 21, use date_from="2026-02-20" and date_to="2026-02-22".

Example Queries

Once connected, you can ask Claude things like:

• "Show me all open conversations"

• "What are the details of conversation #123?"

• "List all messages in conversation #456"

• "Send a reply to conversation #789 saying 'Thank you for contacting us!'"

• "Add an internal note to conversation #101 about the customer's issue"

• "Find all conversations created on Feb 21"

• "Show me resolved conversations from last week with the label 'urgent'"

Development

Project Structure

chatwoot-mcp/
├── src/
│   ├── index.ts                  # MCP server entry point & tool registration
│   ├── constants.ts              # Shared constants and enums
│   ├── chatwoot-types.ts         # Auto-generated OpenAPI types
│   ├── services/
│   │   ├── chatwoot-client.ts    # API client with auth middleware
│   │   ├── chatwoot-auth.ts      # JWT authentication
│   │   ├── token-cache.ts        # JWT token persistence
│   │   └── error-handler.ts      # Error formatting utilities
│   ├── schemas/
│   │   └── common.ts             # Shared Zod validation schemas
│   └── tools/
│       ├── conversations.ts      # List & get conversation tools
│       ├── messages.ts           # List & create message tools
│       └── filter-conversations.ts  # Advanced conversation filtering
├── test/
│   ├── chatwoot-client.test.ts   # Integration tests
│   ├── setup.ts                  # Test environment setup
│   └── unit/                     # Unit tests (mocked, no API calls)
│       ├── error-handler.test.ts
│       ├── build-filter-payload.test.ts
│       ├── conversations.test.ts
│       ├── messages.test.ts
│       ├── filter-conversations.test.ts
│       ├── schemas.test.ts
│       ├── chatwoot-auth.test.ts
│       └── token-cache.test.ts
├── .env.example                  # Environment variable template
├── package.json
├── tsconfig.json
└── vitest.config.ts

Scripts

Regenerating Types

If the Chatwoot API changes, download the latest OpenAPI spec and regenerate types:

1. Download swagger.json from your Chatwoot instance at /swagger/v1/swagger.json

2. Place it in the project root

3. Run npm run generate-types

Running Tests

Unit tests run without any credentials. Integration tests require a real Chatwoot instance:

# Unit tests only (no credentials needed)
npm test -- test/unit/

# All tests (requires .env with valid credentials)
cp .env.example .env
# Edit .env with your credentials
npm test

Troubleshooting

API Token Returns 401

If using a self-hosted Chatwoot with nginx, add this to your nginx config:

server {
    underscores_in_headers on;  # Required for api_access_token header
}

JWT Tokens Expire

JWT tokens expire (typically after 2 weeks). Keep CHATWOOT_PASSWORD in your .env for automatic refresh, or switch to API token authentication.

MCP Connection Errors

If you see JSON parsing errors when connecting, ensure you are using node dist/index.js directly (not npx). Some npm packages output debug information to stdout during installation, which corrupts the MCP stdio protocol.

Tech Stack

• @modelcontextprotocol/sdk - MCP server framework

• openapi-fetch - Type-safe API client

• openapi-typescript - OpenAPI type generation

• Zod - Runtime schema validation

• Vitest - Test framework

Attribution

Originally created by Hugo Blanc.

License

MIT

Contributing

Contributions are welcome! Some ideas for additional tools:

• Contact management (create, update, search)

• Team and agent operations

• Inbox configuration

• Labels and custom attributes

• Reports and analytics