Chatwoot MCP server

Ask Claude about your customer inbox in plain words: who's waiting longest, what a customer wants, everything a company has asked. Hand conversations to an agent or team, label or resolve them, and leave private notes from the same chat, with a confirmation step before anything changes. There is no tool that sends a message to a customer.

Built by Mojood Connect as a working demo for Chatwoot. It runs against any Chatwoot through its application API. This repository includes a local Chatwoot with SAMPLE data for the customer inbox of a made-up company, Harbor Trading, so you can try it without touching a real account.

Tools

How changes are made safe. A call to add_private_note or update_conversation without a confirmation changes nothing: it returns a plain summary ("On conversation 1 with Noor Al-Saadi (Bayt Interiors): put it in the Sales team, assign it to Omar Siddiqui.") and a one-time code. The change happens only when the same request comes back with that code, within 10 minutes. A code works once, and only for the request it was issued for. The server's instructions tell the model to show the summary and wait for the user's yes. Notes carry "via Claude (Mojood Connect demo)", and Chatwoot records every hand-over and label in the conversation under the token's user.

The server acts as the user who owns the access token, with that user's Chatwoot permissions.

Try it locally

Needs Docker (with Compose), uv and Python 3.13.

scripts/reset.sh                         # local Chatwoot on http://localhost:3010, filled with the SAMPLE inbox
uv run --env-file .env chatwoot-mcp      # MCP server on http://127.0.0.1:8004/mcp (Streamable HTTP)

docker/compose.yml follows Chatwoot's own docker-compose.production.yaml (v4.19.1), pinned, with the app on 127.0.0.1 only and the database and Redis not published. scripts/reset.sh generates every password, the account, its admin and the access token itself and keeps them in the git-ignored files docker/.env and .env; nothing is printed. scripts/up.sh starts it again after a restart without touching the data.

Claude Desktop: add this to claude_desktop_config.json (Settings › Developer), with the path to this folder:

{
  "mcpServers": {
    "chatwoot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/chatwoot-mcp", "--env-file", "/path/to/chatwoot-mcp/.env", "chatwoot-mcp", "--stdio"]
    }
  }
}

Then ask: "Who's waiting longest for a reply?", "What does Noor from Bayt Interiors want?", "Give it to Omar in Sales, and note that her client approves budgets on Thursday."

Your own Chatwoot: set CHATWOOT_URL, CHATWOOT_ACCOUNT, CHATWOOT_TOKEN (the access token from your profile settings) and CHATWOOT_SAMPLE=0.

The SAMPLE inbox

Harbor Trading's customer inbox: two API-channel inboxes (Website chat, Email), four agents in two teams (Sales, Service), four labels, eight contacts across seven companies and nine conversations. Message times are set relative to the day it is seeded, so there are always customers waiting for hours, two conversations with no owner, an urgent one, pending ones and resolved history. Everyone and everything in it is made up.

Tests

uv run --env-file .env pytest            # unit tests (a fake Chatwoot API), plus live tests when the local Chatwoot runs

What a production version adds

This demo signs in with one access token. A production server for Chatwoot customers would add sign-in with each agent's own Chatwoot account, so Claude sees exactly the inboxes they may see; hosting with an audit log of every tool call; and more of the API (canned responses, reply drafts for an agent to send, reports, macros, the help center). That is what Mojood Connect builds.

License

Apache 2.0. Chatwoot is a trademark of Chatwoot Inc.; this project is not made or endorsed by Chatwoot Inc.