chatlab-mcp

TypeScript MCP server for ChatLab. It depends on chatlab-cli and starts the ChatLab HTTP API in headless mode by default.

ChatLab CLI command used by default:

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

Install

Use directly with npx:

npx -y l-chris-chatlab-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_AUTO_START | true | Start chatlab-cli automatically before API calls | | CHATLAB_HEADLESS | true | Use --headless; set to false to serve the Web UI too | | 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"
      }
    }
  }
}

After npm publish, you can use npx instead:

{
  "mcpServers": {
    "chatlab": {
      "command": "npx",
      "args": ["-y", "l-chris-chatlab-mcp"],
      "env": {
        "CHATLAB_PORT": "3110",
        "CHATLAB_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Tools

• chatlab_start: start chatlab-cli as a child process.
• 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 against a session database.
• 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.
• The MCP server keeps ChatLab CLI logs on stderr so MCP stdio stays valid.
• ChatLab also has its own CLI MCP mode (chatlab mcp); this project is a wrapper that manages headless HTTP mode and exposes stable API tools.