npm package: @ouyanglouzhu/clickhouse
Description: ClickHouse MCP Server (Python) - 通过 MCP 查询 ClickHouse，供 Cursor/Claude 等使用。npm install 后自动安装 Python 依赖。
Latest version: 0.1.4

# ClickHouse MCP Server（Python）

基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的 ClickHouse 服务端，供 Cursor 等客户端通过工具调用执行查询、查看库表与建表语句。

**分发方式**：仅通过 **npm** 发布，Python 源码与依赖随包一起提供；**不发布到 PyPI**。用户 `npm install` 后由 postinstall 自动安装 Python 依赖，无需手动 `pip install`。

## 功能（Tools）

| 工具名 | 说明 |
|--------|------|
| `clickhouse_query` | 执行只读 SELECT 查询，返回表格形式结果 |
| `clickhouse_list_databases` | 列出所有用户数据库 |
| `clickhouse_list_tables` | 列出指定库下的表（可选 database） |
| `clickhouse_describe_table` | 获取表结构（DESCRIBE TABLE） |
| `clickhouse_get_create_table` | 获取建表语句（SHOW CREATE TABLE） |

## 环境变量

| 变量 | 说明 | 默认 |
|------|------|------|
| `CLICKHOUSE_HOST` | 主机 | 必填 |
| `CLICKHOUSE_PORT` | 原生协议端口 | `9000` |
| `CLICKHOUSE_USER` | 用户名 | `default` |
| `CLICKHOUSE_PASSWORD` | 密码 | 空 |
| `CLICKHOUSE_DATABASE` | 默认数据库 | `default` |

注意：本服务使用 **原生协议**（端口 9000），依赖 `clickhouse-driver`。若你当前只开放了 HTTP（8123），请改用 9000 或开启原生端口。

---

## 安装与使用

### 通过 npm（推荐）

只需安装 npm 包，**无需**单独发布或安装 Python 包：

```bash
npm install @ouyanglouzhu/clickhouse
```

安装时 **postinstall** 会自动执行 `pip install -r requirements.txt`（需本机已安装 Python 3.10+）。若未安装 Python 或安装失败，会提示手动执行：

```bash
pip install -r node_modules/@ouyanglouzhu/clickhouse/python_src/requirements.txt
```

### 在 Cursor 中配置 MCP

本机需已安装 [Node.js](https://nodejs.org/)（和 Python 3.10+，供 postinstall 安装依赖）。在 `.cursor/mcp-config.json` 或全局 MCP 配置中：

```json
{
  "mcpServers": {
    "clickhouse": {
      "command": "npx",
      "args": ["-y", "@ouyanglouzhu/clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "你的主机",
        "CLICKHOUSE_PORT": "9000",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "你的密码",
        "CLICKHOUSE_DATABASE": "default"
      }
    }
  }
}
```

或使用包内二进制（已全局安装时）：

```json
"clickhouse": {
  "command": "mcp-server-clickhouse",
  "args": [],
  "env": { "CLICKHOUSE_HOST": "...", "CLICKHOUSE_PORT": "9000", ... }
}
```

保存后重启 Cursor 或重新加载 MCP 即可。

### 本机有源码时（开发/未发布 npm）

在 `mcp-servers/clickhouse` 目录下：

```bash
cd python_src
pip install -r requirements.txt
python server.py
```

Cursor 中可配置：

```json
"clickhouse": {
  "command": "python",
  "args": ["D:/code/python/dw-sit/mcp-servers/clickhouse/python_src/server.py", "--transport", "stdio"],
  "env": { ... }
}
```

---

## 发布到 npm（不发布到 PyPI）

1. **注册 npm 账号**：https://www.npmjs.com/signup  

2. **在 npm 页面配置 Token（用于发布或 CI）**  
   - 登录 https://www.npmjs.com → 右上角头像 → **Access Tokens**（或直接打开 https://www.npmjs.com/settings/~/tokens）。  
   - 点击 **Generate New Token** → 选择 **Classic Token**。  
   - 权限选 **Automation**（推荐，仅发布）或 **Publish**；若需在网页操作包再选 **Read and write**。  
   - 生成后**只显示一次**，请复制保存；之后在本地或 CI 里用该 token 认证，无需再输入账号密码。  

3. **使用 Token 发布（任选一种）**  

   **方式 A：当前终端临时使用**
   ```bash
   # Windows PowerShell
   $env:NPM_TOKEN="你的token"
   npm config set //registry.npmjs.org/:_authToken=$env:NPM_TOKEN
   ```
   ```bash
   # macOS / Linux
   export NPM_TOKEN=你的token
   npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN
   ```

   **方式 B：用 npm login（交互输入用户名、密码、邮箱、OTP）**  
   若未配 token，可在项目目录执行 `npm login`，按提示输入账号密码后发布。

   **发布命令（在 `mcp-servers/clickhouse` 下执行）**：
   ```bash
   cd mcp-servers/clickhouse
   npm publish --access public
   ```
   本包为 scope 包 `@ouyanglouzhu/clickhouse`，**必须**加 `--access public` 才能免费公开发布，否则会报 402。

   **方式 C：CI（如 GitHub Actions）**  
   在仓库 Settings → Secrets 里添加 `NPM_TOKEN`，workflow 中设置环境变量 `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`，npm 会自动用其作为 registry 认证 token。

4. **包内容**：npm 包内已包含 `python_src/`（含 `server.py`、`requirements.txt`）、`install-python-deps.js` 和 `bin/run.js`，用户安装后即可使用，**无需**再访问 PyPI。

---

## 故障排查

- **显示 “No tools, prompts, or resources”**  
  多为 MCP 进程未正常启动。先在终端执行：
   ```bash
  python node_modules/@ouyanglouzhu/clickhouse/python_src/server.py
  ```
  或（本机路径）：
  ```bash
  python D:\...\mcp-servers\clickhouse\python_src\server.py
  ```
  若报错，按提示安装依赖（`pip install -r python_src/requirements.txt`）或检查 pydantic ≥ 2.0。若进程一直不退出，说明服务正常，问题在 Cursor 的 command/args 或工作目录。

- **`ModuleNotFoundError: No module named 'xxx'`（npx 启动时报缺包）**  
  入口脚本会在启动前检查 `package.json` 里配置的 Python 模块（默认 `mcp`、`clickhouse_driver`、`click`），缺则自动执行 `python -m pip install -r python_src/requirements.txt` 再启动。要检查的模块可在 **package.json** 的 `mcpServer.pythonCheckModules` 中配置（数组，模块名与 `import xxx` 一致）。若仍报错（如无网络或权限），请在本机手动执行一次：
  ```bash
  python -m pip install -r node_modules/@ouyanglouzhu/clickhouse/python_src/requirements.txt
  ```

- **postinstall 报错**  
  若本机无 Python 或 pip 安装失败，不影响 `npm install` 完成。启动时 run.js 会尝试补装依赖；仍失败则请手动在包目录执行：
  ```bash
  pip install -r node_modules/@ouyanglouzhu/clickhouse/python_src/requirements.txt
  ```

## 安全说明

- 工具层仅允许 **SELECT**，不会执行 INSERT/ALTER/DROP 等写操作。
- 密码不要提交到仓库，建议用环境变量或本地配置覆盖。