> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 设置 ClickHouse MCP 服务器
> 将 ClickHouse MCP 服务器连接到 Claude Code、Claude Desktop、Codex、ChatGPT、Cursor 或 Windsurf。
[ClickHouse MCP 服务器](https://github.com/ClickHouse/mcp-clickhouse)可让兼容的 AI 助手浏览数据库、查看表，并对 ClickHouse 运行 SQL 查询。
本指南将使用 `uv` 配置本地 `stdio` 服务器，并将其连接到主流 MCP 客户端。
该服务器默认只允许执行只读查询。
请使用仅授予助手所需权限的专用 ClickHouse 用户，切勿使用 default 或管理用户。
以下步骤以 Claude Desktop 为例演示设置过程。
本指南涵盖的其他客户端同样适用这些 ClickHouse 连接信息。
VIDEO
## 前置条件
开始前：
1. [安装 `uv`](https://docs.astral.sh/uv/getting-started/installation/)。
2. 安装要使用的 MCP 客户端。
3. 获取 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 客户端
在终端中运行以下命令：
```bash theme={null}
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` 中添加以下服务器：
```json theme={null}
{
"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 命令行客户端添加服务器：
```bash theme={null}
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 桌面应用中：
1. 打开 **设置**，然后选择 **MCP 服务器**。
2. 选择 **添加服务器**，然后选择 **STDIO**。
3. 将名称设为 `mcp-clickhouse`，命令设为 `uv`。
4. 按顺序添加 `run`、`--with`、`mcp-clickhouse`、`--python`、`3.10` 和 `mcp-clickhouse` 作为参数。
5. 添加 `CLICKHOUSE_HOST`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD`，并填入你的连接信息。
6. 保存服务器并重启应用。
应用重启后，打开 Codex，并在输入框中输入 `/mcp` 以查看已连接的服务器。
这些步骤会在 ChatGPT 桌面应用中为 Codex 配置本地 `stdio` 服务器。
ChatGPT Web 则使用由插件提供的远程 MCP 工具。
如需在 ChatGPT Web 中使用 ClickHouse 工具，请参阅 [ClickHouse Cloud 中的远程 MCP 服务器](/zh/products/cloud/features/ai-ml/remote-mcp)。
将以下服务器添加到当前项目的 `.cursor/mcp.json` 文件中，或添加到全局 Cursor MCP 配置中：
```json theme={null}
{
"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`：
```json theme={null}
{
"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` 后，向其询问：
```text theme={null}
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](https://github.com/ClickHouse/mcp-clickhouse)。