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, send new messages, and delete messages

• Type-Safe: Built with TypeScript using OpenAPI-generated types

• Flexible Auth: Supports both API token (recommended) and JWT authentication

Related MCP server: @indica-facil/mcp-chatwoot

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

• chatwoot_delete_message - Permanently delete a message and its attachments

Installation

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="your@email.com"
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

Running the Server

npm start

Development Mode (with auto-reload)

npm run dev

Using with Claude Code

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

Using with Claude Desktop

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

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

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"

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

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

Testing

Run integration tests:

npm test

Watch mode:

npm run test:watch

Project Structure

chatwoot-mcp-server/
├── src/
│   ├── index.ts                  # Main server entry point
│   ├── constants.ts              # Shared constants
│   ├── chatwoot-types.ts         # Generated OpenAPI types
│   ├── services/
│   │   ├── chatwoot-client.ts    # API client with auth
│   │   ├── chatwoot-auth.ts      # JWT authentication
│   │   ├── token-cache.ts        # JWT token caching
│   │   └── error-handler.ts      # Error handling utilities
│   ├── schemas/
│   │   └── common.ts             # Shared Zod schemas
│   └── tools/
│       ├── conversations.ts      # Conversation tools
│       └── messages.ts           # Message tools
├── test/                         # Integration tests
├── swagger.json                  # Chatwoot OpenAPI spec
└── package.json

Development

Regenerating Types

If the Chatwoot API changes, regenerate types:

npm run generate-types

Adding New Tools

1. Create a new file in src/tools/

2. Define Zod schemas for input validation

3. Implement the tool function

4. Register the tool in src/index.ts

Building

npm run build

Builds TypeScript to JavaScript in the dist/ directory.

Troubleshooting

API Token Returns 401

If using a self-hosted instance with nginx, ensure underscores_in_headers on; is set in your nginx config. This is required because api_access_token contains underscores.

JWT Tokens Expire

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

Tech Stack

• TypeScript - Type-safe development

• openapi-fetch - Type-safe API client

• openapi-typescript - Generate types from OpenAPI spec

• Zod - Runtime input validation

• @modelcontextprotocol/sdk - MCP server framework

• Vitest - Testing framework

License

MIT

Contributing

Contributions are welcome! Additional tools that could be added:

• Contact management (create, update, search)

• Team and agent operations

• Inbox configuration

• Labels and custom attributes

• Reports and analytics

• Bulk operations

Fork: local build for github.com/vivernet/chatwoot-mcp

This copy is a fork of chatwoot-mcp-server@1.0.0 (see UPSTREAM.md), run from source instead of via npx, with one added tool.

Changes in this fork

• New tool chatwoot_toggle_status — changes a conversation status (open / resolved / pending / snoozed), including optional snoozed_until (Unix timestamp in seconds) for scheduled snooze. Implemented in dist/tools/conversations.js + registered in dist/index.js; uses the stock Chatwoot POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status endpoint (already present in the generated OpenAPI types).

• New tool chatwoot_delete_message — permanently deletes a message and its attachments through Chatwoot's DELETE /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id} endpoint. The tool is marked destructive and requires explicit human approval through the companion chatwoot-approval plugin.

• Version bumped to 1.2.0; start script runs node dist/index.js.

Running locally (no npx)

node dist/index.js

Needs the same env vars as upstream: CHATWOOT_BASE_URL plus either CHATWOOT_API_TOKEN or CHATWOOT_EMAIL/CHATWOOT_PASSWORD.

Smoke test

python3 tests/mcp_smoke.py        # stub HTTP backend; verifies status toggle and message deletion

Hermes Agent wiring

Hermes config.yaml → mcp_servers.chatwoot:

mcp_servers:
  chatwoot:
    command: node
    args: ["/absolute/path/to/chatwoot-mcp-server/dist/index.js"]
    env:
      CHATWOOT_BASE_URL: ${env:CHATWOOT_BASE_URL}
      CHATWOOT_EMAIL: ${env:CHATWOOT_EMAIL}
      CHATWOOT_PASSWORD: ${env:CHATWOOT_PASSWORD}

Companion approval plugin (guards chatwoot_create_message, chatwoot_toggle_status, and chatwoot_delete_message behind the human-approval gate): see the chatwoot-approval Hermes plugin.