# chatlab-cli-mcp

TypeScript MCP server for [ChatLab](https://github.com/ChatLab/ChatLab). It combines direct SQLite analysis tools with `chatlab-cli` headless HTTP service management.

ChatLab CLI command used after local data exists:

```bash
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`:

```bash
npx -y chatlab-cli-mcp
```

Or install from source:

```bash
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

```json
{
  "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:

```json
{
  "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.