设置 ClickHouse MCP 服务器

ClickHouse MCP 服务器可让兼容的 AI 助手浏览数据库、查看表，并对 ClickHouse 运行 SQL 查询。本指南将使用 uv 配置本地 stdio 服务器，并将其连接到主流 MCP 客户端。该服务器默认只允许执行只读查询。请使用仅授予助手所需权限的专用 ClickHouse 用户，切勿使用 default 或管理用户。以下步骤以 Claude Desktop 为例演示设置过程。本指南涵盖的其他客户端同样适用这些 ClickHouse 连接信息。

前置条件

开始前：

安装 uv。
安装要使用的 MCP 客户端。
获取 ClickHouse 服务的主机名、用户名和密码。

以下示例使用了这些占位符值：

环境变量	值
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

请将其替换为实际的连接信息。对于 ClickHouse Cloud 服务，server 默认在端口 8443 上使用 HTTPS。对于使用纯 HTTP 的自管理服务，还需设置 CLICKHOUSE_SECURE=false，并在必要时设置 CLICKHOUSE_PORT=8123。

配置你的 MCP 客户端

在终端中运行以下命令：

claude mcp add \
  --transport stdio \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  --scope user \
  mcp-clickhouse -- \
  uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

运行 claude mcp list 验证连接，或在 Claude Code 中输入 /mcp 查看服务器及其工具。

在 Claude Desktop 中，打开设置，选择 开发者，然后选择 Edit config。在 claude_desktop_config.json 中添加以下服务器：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

保存文件并重启 Claude Desktop。在聊天输入框中打开 Connectors，确认 mcp-clickhouse 是否可用。

通过 Codex 命令行客户端添加服务器：

codex mcp add mcp-clickhouse \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

运行 codex mcp list 验证连接，或在 Codex 终端 UI 中输入 /mcp。 Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用共用 ~/.codex/config.toml 中的 MCP 配置。

ChatGPT 桌面应用会为其 Codex 主机配置本地 MCP 服务器。此配置会与 Codex 命令行客户端和 Codex IDE 扩展共享。在 ChatGPT 桌面应用中：

打开设置，然后选择 MCP 服务器。
选择 添加服务器，然后选择 STDIO。
将名称设为 mcp-clickhouse，命令设为 uv。
按顺序添加 run、--with、mcp-clickhouse、--python、3.10 和 mcp-clickhouse 作为参数。
添加 CLICKHOUSE_HOST、CLICKHOUSE_USER 和 CLICKHOUSE_PASSWORD，并填入你的连接信息。
保存服务器并重启应用。

应用重启后，打开 Codex，并在输入框中输入 /mcp 以查看已连接的服务器。

这些步骤会在 ChatGPT 桌面应用中为 Codex 配置本地 stdio 服务器。 ChatGPT Web 则使用由插件提供的远程 MCP 工具。如需在 ChatGPT Web 中使用 ClickHouse 工具，请参阅 ClickHouse Cloud 中的远程 MCP 服务器。

将以下服务器添加到当前项目的 .cursor/mcp.json 文件中，或添加到全局 Cursor MCP 配置中：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

重新启动 Cursor，然后打开其 MCP 设置，确认服务器已启用。

将以下服务器配置添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse-host",
        "CLICKHOUSE_USER": "your-clickhouse-user",
        "CLICKHOUSE_PASSWORD": "your-clickhouse-password"
      }
    }
  }
}

重新加载 Windsurf，然后打开其 MCP 设置，确认服务器已启用。

验证连接

客户端报告已连接到 mcp-clickhouse 后，向其询问：

List the databases available in ClickHouse, then show me the tables in one of them.

客户端可能会要求您批准首次调用工具。授予访问权限前，请审核每个请求。

故障排查

如果客户端提示无法找到 uv，请将命令或配置中的 uv 替换为其绝对路径。在 macOS 或 Linux 上运行 which uv，或在 Windows 上运行 where uv，即可找到该路径。有关其他连接设置、可选的 chDB 支持、HTTP 传输和身份验证，请参阅 mcp-clickhouse README。

ClickHouse guides

Use case guides

前置条件

配置你的 MCP 客户端

验证连接

故障排查

​前置条件

​配置你的 MCP 客户端

​验证连接

​故障排查

前置条件

配置你的 MCP 客户端

验证连接

故障排查