chatlab-mcp

English | 简体中文 | 繁體中文 | 日本語

MCP server that connects ChatLab to AI assistants (Claude Desktop, Cursor, custom agents). Query your local chat history with natural language.

Tracks ChatLab v0.19.0

Requirements

• ChatLab installed and running
• API enabled in ChatLab Settings → API, with a token generated
• Node.js 18+

Installation

npx (recommended)

No installation needed. Configure your AI client directly:

{
  "mcpServers": {
    "chatlab": {
      "command": "npx",
      "args": ["-y", "chatlab-mcp"],
      "env": {
        "CHATLAB_TOKEN": "clb_xxxxxxxxxxxx",
        "CHATLAB_URL": "http://127.0.0.1:5200"
      }
    }
  }
}

From source

git clone https://github.com/gamesme/chatlab-mcp
cd chatlab-mcp
npm install && npm run build

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

With npx:

{
  "mcpServers": {
    "chatlab": {
      "command": "npx",
      "args": ["-y", "chatlab-mcp"],
      "env": {
        "CHATLAB_TOKEN": "clb_xxxxxxxxxxxx",
        "CHATLAB_URL": "http://127.0.0.1:5200"
      }
    }
  }
}

From source (use your Homebrew node to avoid version issues):

{
  "mcpServers": {
    "chatlab": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/chatlab-mcp/dist/index.js"],
      "env": {
        "CHATLAB_TOKEN": "clb_xxxxxxxxxxxx",
        "CHATLAB_URL": "http://127.0.0.1:5200"
      }
    }
  }
}

Restart Claude Desktop after saving. The chatlab tools will appear in the tools list.

Tools

Core (6)

Tool	Description
list_sessions	List all imported chat sessions with name, platform, and message count
get_session	Get details of a single session by ID
get_messages	Retrieve messages with filters: keyword, time range, sender, pagination (max 100/call)
get_members	List all members in a session with their platformId and message count
get_stats_overview	Statistical overview: message counts, member activity, type distribution, time range
execute_sql	Run aggregation queries (COUNT/GROUP BY) against the session database

Analytics (v0.19.0+, 9)

Tool	Description
get_message_context	N messages before/after one or more target message IDs
get_conversation_between	Interleaved messages between two specific members (numeric IDs)
get_session_summaries	AI-generated chat sub-session summaries (from the chat_session table)
deep_search_messages	FTS5 keyword search with surrounding context window
get_time_stats	Hourly / weekday / daily distribution, timezone-aware
get_member_activity	Top-N members by message count with percentage of total
get_member_name_history	Historical account name / nickname entries for a member
get_response_time_analysis	Reply intervals between sender pairs (LAG window function)
keyword_frequency	Stub — returns guidance (NLP segmentation not bundled in MCP)

Notes

• get_messages returns at most 100 messages per call. Use the page parameter to paginate. Responses include has_more and a hint when more results exist.
• execute_sql is for statistical aggregation only. Use get_messages or get_message_context to read message content.
• Analytics tools issue their own SQL through the same /sql endpoint (no 200-row LIMIT injection).
• All avatar/binary fields are stripped from responses to minimize context usage.

CLI Options

node dist/index.js --token <token> --url <url>
# or via env vars
CHATLAB_TOKEN=clb_xxx CHATLAB_URL=http://127.0.0.1:5200 node dist/index.js

CHATLAB_URL defaults to http://127.0.0.1:5200.

Development

npm test             # run all tests
npm run test:watch   # watch mode
npm run dev          # run with ts-node (no build step)
npm run build        # compile TypeScript → dist/