ClickHouse MCP Server（Python）

基于 Model Context Protocol 的 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 包：

npm install @ouyanglouzhu/clickhouse

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

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

在 Cursor 中配置 MCP

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

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

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

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

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

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

在 mcp-servers/clickhouse 目录下：

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

Cursor 中可配置：

"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：当前终端临时使用

   # Windows PowerShell
   $env:NPM_TOKEN="你的token"
   npm config set //registry.npmjs.org/:_authToken=$env:NPM_TOKEN

   # 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 下执行）：

   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 进程未正常启动。先在终端执行：

  python node_modules/@ouyanglouzhu/clickhouse/python_src/server.py

  或（本机路径）：

  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 一致）。若仍报错（如无网络或权限），请在本机手动执行一次：

  python -m pip install -r node_modules/@ouyanglouzhu/clickhouse/python_src/requirements.txt

• postinstall 报错
  若本机无 Python 或 pip 安装失败，不影响 npm install 完成。启动时 run.js 会尝试补装依赖；仍失败则请手动在包目录执行：

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

安全说明

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