chatlab-cli-mcp

TypeScript MCP server for ChatLab. It combines direct SQLite analysis tools with chatlab-cli headless HTTP service management.

ChatLab CLI command used after local data exists:

chatlab start --headless --host 127.0.0.1 --port 3110 --token <token>

On first run, when no ChatLab session database is found locally, the server starts ChatLab without --headless and allows the Web UI to open so you can import or configure data. After local data exists, startup does not open a browser automatically; use chatlab_open_ui when you want the page.

Install

Use directly with npx:

npx -y chatlab-cli-mcp

Or install from source:

npm install
npm run build

Related MCP server: wrapmcp

Configuration

MCP client example

{
  "mcpServers": {
    "chatlab": {
      "command": "node",
      "args": ["/home/projects/wechat-tool/chatlab-mcp/dist/index.js"],
      "env": {
        "CHATLAB_PORT": "3110",
        "CHATLAB_TOKEN": "YOUR_TOKEN",
        "CHATLAB_DATA_DIR": "/path/to/chatlab/data"
      }
    }
  }
}

After npm publish, you can use npx instead:

{
  "mcpServers": {
    "chatlab": {
      "command": "npx",
      "args": ["-y", "chatlab-cli-mcp"],
      "env": {
        "CHATLAB_PORT": "3110",
        "CHATLAB_TOKEN": "YOUR_TOKEN",
        "CHATLAB_DATA_DIR": "/path/to/chatlab/data"
      }
    }
  }
}

Tools

• chatlab_start: start chatlab-cli as a child process.

• chatlab_open_ui: start or restart with the Web UI enabled and open it in the browser.

• chatlab_stop: stop the child process started by this MCP server.

• chatlab_status: show process state and ChatLab /api/v1/status.

• chatlab_list_sessions: list imported chat sessions.

• chatlab_get_session: get one session's metadata.

• chatlab_get_messages: page messages from a session.

• chatlab_get_members: list members in a session.

• chatlab_get_overview: get session overview stats.

• chatlab_execute_sql: run readonly SQL directly against a session database.

• chatlab_get_schema: get the SQLite schema.

• chatlab_search_messages: search messages by keywords.

• chatlab_deep_search_messages: exact substring search.

• chatlab_get_recent_messages: fetch recent messages.

• chatlab_get_message_context: fetch context around a message.

• chatlab_get_member_stats: member activity ranking.

• chatlab_get_time_stats: hourly, weekday, or daily activity.

• chatlab_get_conversation_between: messages involving two members.

• chatlab_response_time_analysis: estimate response speed.

• chatlab_keyword_frequency: simple local keyword frequency.

• chatlab_get_segment_summaries: list generated conversation segments.

• chatlab_get_segment_messages: get messages in one segment.

• chatlab_export_session: export one session in ChatLab format.

• chatlab_import_session: import ChatLab-format JSON into a session ID.

• chatlab_request: call any ChatLab HTTP API endpoint.

Notes

• ChatLab's default API port is 3110.

• Core reading and analysis tools access SQLite directly and do not require the HTTP service.

• If no local session databases are found, auto-start opens the Web UI for first-time setup.

• After local data exists, startup does not open the browser automatically; call chatlab_open_ui to open the page.

• The MCP server keeps ChatLab CLI logs on stderr so MCP stdio stays valid.

• Import/export and custom API calls use chatlab-cli headless HTTP mode.