Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@chatlab-mcp list my recent chat sessions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
ChatLab installed and running
API enabled in ChatLab Settings → API, with a token generated
Node.js 18+
Related MCP server: mcp-copilotcli-history
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"
}
}
}
}git clone https://github.com/gamesme/chatlab-mcp
cd chatlab-mcp
npm install && npm run buildEdit ~/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.
Tool | Description |
| List all imported chat sessions with name, platform, and message count |
| Get details of a single session by ID |
| Retrieve messages with filters: keyword, time range, sender, pagination (max 100/call) |
| List all members in a session with their platformId and message count |
| Statistical overview: message counts, member activity, type distribution, time range |
| Run aggregation queries (COUNT/GROUP BY) against the session database |
Tool | Description |
| N messages before/after one or more target message IDs |
| Interleaved messages between two specific members (numeric IDs) |
| AI-generated chat sub-session summaries (from the chat_session table) |
| FTS5 keyword search with surrounding context window |
| Hourly / weekday / daily distribution, timezone-aware |
| Top-N members by message count with percentage of total |
| Historical account name / nickname entries for a member |
| Reply intervals between sender pairs (LAG window function) |
| Stub — returns guidance (NLP segmentation not bundled in MCP) |
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.
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.jsCHATLAB_URL defaults to http://127.0.0.1:5200.
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/Full-text search messages via FTS5, then expand each hit with surrounding context messages. Use for "did anyone mention X" style queries where conversation context matters.
Inputs: session_id (required), keywords (required), sender_id, start_time, +6 more.
For statistical aggregation ONLY (COUNT, GROUP BY, SUM, AVG). Do NOT use to fetch message content — use get_messages for that. Max 200 rows returned. Available tables: message, member.
Inputs: session_id (required), query (required).
Get messages between two specific members (interleaved by time). Use when the user asks "what did A and B talk about". Members must be referenced by their numeric DB id; call get_members first to look them up.
Inputs: session_id (required), member_id_1 (required), member_id_2 (required), start_time, +4 more.
Get conversation in plain text format with filtering and compression. Returns compact text optimized for LLM context (saves tokens vs JSON).
Inputs: session_id (required), start_time, end_time, sender_id, +3 more.
Get full conversation across multiple pages, returns compact text format. Use for small to medium sessions only.
Inputs: session_id (required), max_total_messages, merge_consecutive, filter_invalid.
Top members ranked by message count with percentage of total. Use for "who talks the most" or "most active members" type questions. Supports top_n and time filters.
Inputs: session_id (required), top_n, start_time, end_time, +1 more.
Get the historical name changes (account name, nickname) for a single member. Useful for tracking identity changes over time.
Inputs: session_id (required), member_id (required), format, timezone.
Lists all members in a session with their platformId, name, and role. Returns plain text by default (set format=json for JSON).
Inputs: session_id (required), format.
Get N messages before and after one or more specific message IDs. Use when the user references "what was being said around message X" or wants to see the conversation surrounding a specific message.
Inputs: session_id (required), message_ids (required), context_size, format, +1 more.
The primary tool for reading message content. Retrieves up to 500 messages per call with filters for keyword, time range, and sender. Use page to paginate. Returns plain text by default (set format=json for JSON, format=text for compact format). Always prefer this over execute_sql when reading messages.
Inputs: session_id (required), keyword, start_time, end_time, +8 more.
Reply intervals between consecutive messages from different senders, grouped by (from, to) pair. Excludes same-sender continuations and gaps over 1 hour. Use for "who responds fastest" type questions.
Inputs: session_id (required), top_n, start_time, end_time, +1 more.
Gets full details of a single session by ID. Returns plain text by default (set format=json for JSON).
Inputs: id (required), format.
Get AI-generated summaries of chat sub-sessions from the chat_session table. Use to quickly survey what topics have been discussed. Supports keyword filtering and time range. Returns text by default.
Inputs: session_id (required), keywords, limit, start_time, +3 more.
Returns statistical overview of a session: message counts, active members, time distribution. Returns plain text by default (set format=json for JSON).
Inputs: session_id (required), format.
Get message count distribution bucketed by hour, weekday, or day. Use for "when are people most active" type questions. Timezone-aware bucketing.
Inputs: session_id (required), type (required), start_time, end_time, +2 more.
Word/keyword frequency analysis. Currently not implemented in the MCP server due to NLP dependency size; returns a stub message with alternative approaches.
Inputs: session_id (required), format.
Lists all imported chat sessions with name, platform, message count, and time range. Returns plain text by default (set format=json for JSON).
Inputs: format.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Most tools have clearly distinct purposes, but there is slight overlap between get_messages, get_conversation_text, and get_full_conversation. However, descriptions clarify when to use each, so ambiguity is low.
All tools follow a consistent verb_noun pattern with snake_case. Most use 'get_' prefix, except deep_search_, execute_sql, keyword_frequency, and list_sessions, which are still clear and consistent with their verb choice.
17 tools is slightly above the typical well-scoped range (3-15), but each tool serves a distinct analytical purpose for chat sessions, so it feels appropriate rather than bloated.
The tool set covers all major aspects of chat analysis (listing, messages, members, activity, time stats, context, summaries). The only gap is the stub keyword_frequency tool, which is acknowledged but not implemented.
Query your app's logs, metrics and incidents from your AI assistant.
Query your Logspot analytics, companies, and revenue from any AI assistant, and run your actions.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
