---
title: "连接 ClickHouse 本地 MCP"
summary: "通过 uv 启动 mcp-clickhouse，并使用 env_vars 提供连接信息与密码。默认采用只读查询，独立于 Cloud 托管服务。"
category: mcp
level: starter
surfaces: [cli, app, ide]
tags: ["MCP", "ClickHouse", "stdio", "env_vars"]
canonical: /tips/mcp-clickhouse-stdio/
---

# 连接 ClickHouse 本地 MCP

通过 uv 启动 mcp-clickhouse，并使用 env_vars 提供连接信息与密码。默认采用只读查询，独立于 Cloud 托管服务。

ClickHouse 文档包含 Codex 配置说明：本机 **stdio** 包 `mcp-clickhouse`，经 HTTP 接口去查**你的**集群（Cloud 主机或自建都行）。这不是托管 `mcp.clickhouse.cloud/mcp`，也不是 ClickStack 的 `/clickstack`。官方表名就是 `mcp-clickhouse`。

先装 `uv`，并确认有路径：

```bash
which uv
```

`which uv` 必须返回路径。缺了去官方 uv 页安装，不要把那条 curl 管道当成 Codex 主路径。

然后才登记。文档那条 `--env CLICKHOUSE_PASSWORD=your-clickhouse-password` 会把密钥写进 `config.toml`，**不要抄**。先 add 命令，再改 TOML：

```bash
codex mcp add mcp-clickhouse -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse
```

```toml
[mcp_servers.mcp-clickhouse]
command = "uv"
args = ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"]
env_vars = ["CLICKHOUSE_HOST", "CLICKHOUSE_USER", "CLICKHOUSE_PASSWORD"]
startup_timeout_sec = 60
enabled = true

[mcp_servers.mcp-clickhouse.env]
CLICKHOUSE_SECURE = "true"
```

`CLICKHOUSE_HOST` / `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` 必须在**启动 Codex 的那个进程**里。Codex 不读 `.env`。Cloud 服务默认 HTTPS，端口默认 `8443`，保持 `CLICKHOUSE_SECURE = "true"`。自建明文 HTTP 才改成 `"false"`，并把 `CLICKHOUSE_PORT` 加进 `env_vars`（常见是 `8123`）。建议为查询创建独立的只读用户。

这是本地 stdio 服务，无需 OAuth 登录。冷 `uv run --with` 第一次拉包经常超过默认 10 秒，所以加上 `startup_timeout_sec = 60`。默认查询只读（`CLICKHOUSE_ALLOW_WRITE_ACCESS` 为 false）。写入和删除权限需按实际任务单独配置。

相关服务与配置：

- Cloud 托管 MCP 是 `codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp`，再 OAuth。那张表名是 `clickhouse-cloud`。
- ClickStack 观测端点是 `https://mcp.clickhouse.cloud/clickstack`。官方 ClickStack 页没有 Codex 专节，不要当这条的主路径。
- 公共插件目录 `/plugins` 搜 ClickHouse 捆绑的是托管远程 MCP，不是这台本机 `uv` 进程。

网页 Cloud 读不到这台本机 stdio。配置后重新打开会话。用 `codex mcp get mcp-clickhouse` 看 command 是 `uv`。`/mcp` 里工具 0 先查超时、`which uv` 和进程环境。

## 来源

- [ClickHouse · Set up MCP server](https://clickhouse.com/docs/guides/use-cases/ai-ml/MCP/claude-desktop)
- [ClickHouse/mcp-clickhouse](https://github.com/ClickHouse/mcp-clickhouse)
- [ClickHouse · ClickStack MCP](https://clickhouse.com/docs/clickstack/mcp)