Skip to main content
Glama
chatlab-mcp

chatlab-mcp

by L-Chris

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

Variable

Default

Description

CHATLAB_PORT

3110

ChatLab HTTP API port

CHATLAB_API_PORT

empty

Fallback port variable if CHATLAB_PORT is not set

CHATLAB_HOST

127.0.0.1

ChatLab listen host

CHATLAB_TOKEN

generated per MCP process

Bearer token passed to chatlab-cli and used for API calls

CHATLAB_DATA_DIR

~/.chatlab/data

ChatLab data root used by direct SQLite tools; databases live under <data>/databases

CHATLAB_AUTO_START

true

Start chatlab-cli automatically before API calls

CHATLAB_HEADLESS

true

Use --headless after local data exists; first run without data opens the Web UI

CHATLAB_TIMEOUT_MS

30000

HTTP request timeout

CHATLAB_CLI_BIN

bundled chatlab-cli

Optional custom executable or script path

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.

Available Tools

12 tools
chatlab_execute_sqlB

Execute readonly SQL against a ChatLab session database.

Inputs: sql (required), sessionId (required).

chatlab_export_sessionB

Export one ChatLab session as ChatLab-format JSON.

Inputs: sessionId (required).

chatlab_get_membersC

List members in a ChatLab session.

Inputs: sessionId (required).

chatlab_get_messagesC

Get paginated messages from a ChatLab session.

Inputs: sessionId (required), page, limit, endTime, +3 more.

chatlab_get_overviewC

Get overview stats for a ChatLab session.

Inputs: sessionId (required).

chatlab_get_sessionA

Get metadata for one imported ChatLab session.

Inputs: sessionId (required).

chatlab_import_sessionC

Import a ChatLab-format JSON payload into a session ID.

Inputs: payload (required), sessionId (required).

chatlab_list_sessionsB

List imported ChatLab sessions.

Inputs: no named parameters.

chatlab_requestA

Call any ChatLab HTTP API endpoint. Use this for endpoints not covered by dedicated tools.

Inputs: path (required), body, query, method.

chatlab_startB

Start chatlab-cli in headless HTTP API mode. Port defaults to CHATLAB_PORT or 3110.

Inputs: host, port, headless.

chatlab_statusA

Get local process state and ChatLab API status.

Inputs: no named parameters.

chatlab_stopA

Stop the chatlab-cli child process started by this MCP server.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct action—SQL execution, session export/import, listing, metadata retrieval, members, messages, overview, generic API call, and process management. No two tools have overlapping functionality, making it easy for an agent to select the correct one.

    Naming Consistency4/5

    All tools use the 'chatlab_' prefix and snake_case. Most follow a verb_noun pattern (e.g., execute_sql, list_sessions), but 'chatlab_request' uses a noun as the verb, and the process commands (start, stop, status) omit a noun, breaking the pattern slightly.

    Tool Count5/5

    With 12 tools, the set is well-scoped for managing ChatLab sessions: it covers session CRUD, data retrieval, SQL execution, process lifecycle, and a generic fallback. Neither too few nor too many for the domain.

    Completeness4/5

    The tools cover core session management (list, get, import, export, execute SQL, view members/messages/overview) and process control. Missing explicit update/delete operations, but the generic 'chatlab_request' tool can be used to fill gaps, preventing agent dead ends.

    Related MCP Connectors

    Related MCP Servers