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

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.