mcp-chatwoot 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# mcp-chatwoot
+
+MCP server **read-only** para Chatwoot — lista conversas, lê mensagens e busca em qualquer inbox (WhatsApp, e-mail, API, etc).
+
+Funciona em qualquer client MCP: **Claude Code, Cursor, VS Code (Copilot/Cline/Continue), Windsurf, Antigravity, Zed**.
+
+Dois transportes: **stdio** (default, recomendado) e **HTTP** (com bearer token opcional pra expor pra rede).
+
+---
+
+## Tools
+
+| Tool | Descrição |
+|---|---|
+| `list_conversations` | Lista conversas (filtros: status, page, labels, inbox_id). |
+| `read_conversation_messages` | Mensagens de uma conversa (texto, autor, timestamp, anexos). |
+| `search_messages` | Busca full-text em mensagens. |
+| `summarize_conversation` | Resumo: participantes, contagem por autor, primeira/última mensagem, anexos. |
+
+---
+
+## Variáveis de ambiente
+
+| Var | Obrigatório | Default | Descrição |
+|---|---|---|---|
+| `CHATWOOT_URL` | sim | `http://localhost:3000` | URL do Chatwoot. |
+| `CHATWOOT_TOKEN` | sim | — | API access token (em Profile → Access Token). |
+| `CHATWOOT_ACCOUNT_ID` | não | `1` | ID da conta. |
+| `CHATWOOT_INBOX_ID` | não | — | Trava o MCP em um inbox. Vazio = toda a conta. |
+| `CHATWOOT_INBOX_LABEL` | não | — | Apenas pra documentar (ex: "Techmax WhatsApp"). |
+| `MCP_TRANSPORT` | não | `stdio` | `stdio` ou `http`. |
+| `PORT` | não | `8765` | Porta HTTP (se `MCP_TRANSPORT=http`). |
+| `MCP_AUTH_TOKEN` | não | — | Se setado, exige `Authorization: Bearer <token>` (só HTTP). |
+
+---
+
+## Instalação
+
+### Claude Code
+
+```bash
+claude mcp add chatwoot \
+  -e CHATWOOT_URL=https://seu-chatwoot.com \
+  -e CHATWOOT_TOKEN=SEU_TOKEN \
+  -e CHATWOOT_INBOX_ID=2 \
+  -- npx -y mcp-chatwoot
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "chatwoot": {
+      "command": "npx",
+      "args": ["-y", "mcp-chatwoot"],
+      "env": {
+        "CHATWOOT_URL": "https://seu-chatwoot.com",
+        "CHATWOOT_TOKEN": "SEU_TOKEN",
+        "CHATWOOT_INBOX_ID": "2"
+      }
+    }
+  }
+}
+```
+
+### VS Code (extensões com MCP: Cline, Continue, Copilot)
+
+Em `.vscode/mcp.json` ou settings da extensão:
+
+```json
+{
+  "servers": {
+    "chatwoot": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-chatwoot"],
+      "env": {
+        "CHATWOOT_URL": "https://seu-chatwoot.com",
+        "CHATWOOT_TOKEN": "SEU_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Windsurf / Antigravity / Zed
+
+Mesma config de stdio do Cursor — adapte o arquivo de config do client (geralmente `mcp.json` ou painel de MCP servers nas settings).
+
+### Docker (HTTP transport)
+
+```bash
+docker run -d \
+  --name mcp-chatwoot \
+  -p 8765:8765 \
+  -e MCP_TRANSPORT=http \
+  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
+  -e CHATWOOT_URL=https://seu-chatwoot.com \
+  -e CHATWOOT_TOKEN=SEU_TOKEN \
+  -e CHATWOOT_INBOX_ID=2 \
+  ghcr.io/REPLACE_ME/mcp-chatwoot:latest
+```
+
+Depois no client (Claude Code):
+
+```bash
+claude mcp add --transport http chatwoot http://SERVER:8765/mcp \
+  --header "Authorization: Bearer SEU_MCP_AUTH_TOKEN"
+```
+
+---
+
+## Rodar local sem instalar
+
+```bash
+git clone <repo>
+cd mcp-chatwoot
+npm install
+npm run build
+CHATWOOT_URL=... CHATWOOT_TOKEN=... node dist/index.js
+```
+
+---
+
+## Licença
+
+MIT

package/dist/chatwoot.js

@@ -0,0 +1,47 @@
+const CHATWOOT_URL = (process.env.CHATWOOT_URL ?? "http://localhost:3000").replace(/\/$/, "");
+const CHATWOOT_TOKEN = process.env.CHATWOOT_TOKEN ?? "";
+const ACCOUNT_ID = process.env.CHATWOOT_ACCOUNT_ID ?? "1";
+const RAW_INBOX = process.env.CHATWOOT_INBOX_ID ?? "";
+export const CHATWOOT_INBOX_ID = RAW_INBOX ? Number(RAW_INBOX) : undefined;
+export const CHATWOOT_INBOX_LABEL = process.env.CHATWOOT_INBOX_LABEL ?? "";
+if (!CHATWOOT_TOKEN) {
+    process.stderr.write("[mcp-chatwoot] WARN: CHATWOOT_TOKEN not set\n");
+}
+const BASE = `${CHATWOOT_URL}/api/v1/accounts/${ACCOUNT_ID}`;
+async function cw(path, params) {
+    const url = new URL(`${BASE}${path}`);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+    }
+    const res = await fetch(url.toString(), {
+        headers: { api_access_token: CHATWOOT_TOKEN, "Content-Type": "application/json" },
+    });
+    if (!res.ok) {
+        throw new Error(`Chatwoot ${res.status}: ${await res.text()}`);
+    }
+    return res.json();
+}
+export async function listConversations(opts) {
+    const inbox = CHATWOOT_INBOX_ID ?? opts.inboxOverride;
+    const data = await cw("/conversations", {
+        inbox_id: inbox,
+        status: opts.status ?? "all",
+        page: opts.page ?? 1,
+        labels: opts.labels?.join(","),
+    });
+    return data.data;
+}
+export async function getConversationMessages(conversationId) {
+    const data = await cw(`/conversations/${conversationId}/messages`);
+    return data.payload;
+}
+export async function getConversation(conversationId) {
+    return cw(`/conversations/${conversationId}`);
+}
+export async function searchMessages(q, page = 1) {
+    const data = await cw("/conversations/search", { q, page });
+    return data.payload;
+}

package/dist/index.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { listConversations, getConversationMessages, getConversation, searchMessages, CHATWOOT_INBOX_ID, CHATWOOT_INBOX_LABEL, } from "./chatwoot.js";
+const TRANSPORT = (process.env.MCP_TRANSPORT ?? "stdio").toLowerCase();
+const PORT = Number(process.env.PORT ?? 8765);
+const AUTH_TOKEN = process.env.MCP_AUTH_TOKEN;
+function buildServer() {
+    const server = new McpServer({
+        name: "chatwoot",
+        version: "0.2.0",
+    });
+    const inboxNote = CHATWOOT_INBOX_ID
+        ? `Escopo fixo: inbox_id=${CHATWOOT_INBOX_ID}${CHATWOOT_INBOX_LABEL ? ` (${CHATWOOT_INBOX_LABEL})` : ""}.`
+        : "Escopo: toda a conta Chatwoot (configure CHATWOOT_INBOX_ID pra restringir).";
+    server.registerTool("list_conversations", {
+        description: `Lista conversas do Chatwoot. ${inboxNote}`,
+        inputSchema: {
+            status: z.enum(["open", "resolved", "pending", "snoozed", "all"]).optional(),
+            page: z.number().int().min(1).optional(),
+            labels: z.array(z.string()).optional(),
+            inbox_id: z
+                .number()
+                .int()
+                .optional()
+                .describe("Override do inbox (ignorado se CHATWOOT_INBOX_ID estiver setado no servidor)."),
+        },
+    }, async ({ status, page, labels, inbox_id }) => {
+        const data = await listConversations({ status, page, labels, inboxOverride: inbox_id });
+        const slim = data.payload.map((c) => ({
+            id: c.id,
+            status: c.status,
+            inbox_id: c.inbox_id,
+            contact: c.meta?.sender?.name ?? c.meta?.sender?.phone_number ?? c.meta?.sender?.identifier,
+            last_message: c.last_non_activity_message?.content?.slice(0, 200),
+            last_at: c.last_non_activity_message?.created_at,
+            labels: c.labels,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify({ meta: data.meta, conversations: slim }, null, 2) }],
+        };
+    });
+    server.registerTool("read_conversation_messages", {
+        description: "Lê todas as mensagens de uma conversa (texto, autor, timestamp, anexos).",
+        inputSchema: {
+            conversation_id: z.number().int(),
+            only_text: z.boolean().optional().describe("Se true, oculta atividades do sistema."),
+        },
+    }, async ({ conversation_id, only_text }) => {
+        const msgs = await getConversationMessages(conversation_id);
+        const filtered = only_text ? msgs.filter((m) => m.message_type !== 2) : msgs;
+        return {
+            content: [{ type: "text", text: JSON.stringify(filtered.map(formatMessage), null, 2) }],
+        };
+    });
+    server.registerTool("search_messages", {
+        description: `Busca full-text em mensagens do Chatwoot. ${CHATWOOT_INBOX_ID ? `Resultado filtrado pelo inbox=${CHATWOOT_INBOX_ID}.` : "Sem filtro de inbox."}`,
+        inputSchema: {
+            q: z.string().min(2),
+            page: z.number().int().min(1).optional(),
+        },
+    }, async ({ q, page }) => {
+        const result = await searchMessages(q, page ?? 1);
+        const conversations = CHATWOOT_INBOX_ID
+            ? result.conversations.filter((c) => c.inbox_id === CHATWOOT_INBOX_ID)
+            : result.conversations;
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ conversations, messages: result.messages }, null, 2) },
+            ],
+        };
+    });
+    server.registerTool("summarize_conversation", {
+        description: "Resumo estruturado de uma conversa: participantes, total de mensagens, primeira/última, anexos.",
+        inputSchema: { conversation_id: z.number().int() },
+    }, async ({ conversation_id }) => {
+        const [conv, msgs] = await Promise.all([
+            getConversation(conversation_id),
+            getConversationMessages(conversation_id),
+        ]);
+        const real = msgs.filter((m) => m.message_type !== 2);
+        const bySender = new Map();
+        for (const m of real) {
+            const k = m.sender?.name ?? m.sender?.type ?? "desconhecido";
+            bySender.set(k, (bySender.get(k) ?? 0) + 1);
+        }
+        const first = real[0];
+        const last = real[real.length - 1];
+        const attachments = real.flatMap((m) => m.attachments ?? []);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        conversation_id: conv.id,
+                        status: conv.status,
+                        inbox_id: conv.inbox_id,
+                        contact: conv.meta?.sender,
+                        total_messages: real.length,
+                        participants: Array.from(bySender, ([name, count]) => ({ name, count })),
+                        first_message: first ? formatMessage(first) : null,
+                        last_message: last ? formatMessage(last) : null,
+                        attachments_count: attachments.length,
+                        attachment_types: Array.from(new Set(attachments.map((a) => a.file_type))),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    return server;
+}
+function formatMessage(m) {
+    const direction = m.message_type === 0 ? "in" : m.message_type === 1 ? "out" : "sys";
+    return {
+        id: m.id,
+        at: new Date(m.created_at * 1000).toISOString(),
+        direction,
+        from: m.sender?.name ?? m.sender?.type ?? null,
+        phone: m.sender?.phone_number ?? null,
+        content_type: m.content_type,
+        text: m.content,
+        attachments: (m.attachments ?? []).map((a) => ({ type: a.file_type, url: a.data_url })),
+    };
+}
+async function runStdio() {
+    const transport = new StdioServerTransport();
+    await buildServer().connect(transport);
+    process.stderr.write(`[mcp-chatwoot] stdio ready (inbox=${CHATWOOT_INBOX_ID ?? "all"})\n`);
+}
+async function runHttp() {
+    const { default: express } = await import("express");
+    const { randomUUID } = await import("node:crypto");
+    const app = express();
+    app.use(express.json({ limit: "4mb" }));
+    if (AUTH_TOKEN) {
+        app.use((req, res, next) => {
+            if (req.path === "/health")
+                return next();
+            const h = req.headers.authorization ?? "";
+            if (h !== `Bearer ${AUTH_TOKEN}`) {
+                res.status(401).json({ error: "unauthorized" });
+                return;
+            }
+            next();
+        });
+    }
+    const transports = new Map();
+    app.post("/mcp", async (req, res) => {
+        const sid = req.headers["mcp-session-id"];
+        let transport = sid ? transports.get(sid) : undefined;
+        if (!transport && isInitializeRequest(req.body)) {
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                    transports.set(id, transport);
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    transports.delete(transport.sessionId);
+            };
+            await buildServer().connect(transport);
+        }
+        if (!transport) {
+            res
+                .status(400)
+                .json({ jsonrpc: "2.0", error: { code: -32000, message: "No valid session" }, id: null });
+            return;
+        }
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get("/mcp", async (req, res) => {
+        const sid = req.headers["mcp-session-id"];
+        const t = sid ? transports.get(sid) : undefined;
+        if (!t) {
+            res.status(400).send("No session");
+            return;
+        }
+        await t.handleRequest(req, res);
+    });
+    app.delete("/mcp", async (req, res) => {
+        const sid = req.headers["mcp-session-id"];
+        const t = sid ? transports.get(sid) : undefined;
+        if (!t) {
+            res.status(400).send("No session");
+            return;
+        }
+        await t.handleRequest(req, res);
+    });
+    app.get("/health", (_req, res) => res.json({ ok: true, inbox: CHATWOOT_INBOX_ID ?? null, auth: !!AUTH_TOKEN }));
+    app.listen(PORT, () => {
+        console.log(`[mcp-chatwoot] http :${PORT} (inbox=${CHATWOOT_INBOX_ID ?? "all"}, auth=${!!AUTH_TOKEN})`);
+    });
+}
+if (TRANSPORT === "http") {
+    runHttp().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}
+else {
+    runStdio().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mcp-chatwoot",
+  "version": "0.2.0",
+  "description": "MCP server read-only para Chatwoot — funciona com Claude Code, Cursor, VS Code, Antigravity, Windsurf, Cline e qualquer client MCP. Stdio + HTTP transports.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-chatwoot": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "start:http": "MCP_TRANSPORT=http node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "chatwoot",
+    "whatsapp",
+    "claude",
+    "cursor",
+    "antigravity"
+  ],
+  "author": "João Pedro Moreira <joaop13sobra@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "express": "^4.21.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}