- 一个正在运行的 ClickHouse Cloud 服务
- 你选择的 IDE 或智能体开发工具
- 如需进行无头 (headless) 身份验证,还需要一个有权访问所需组织和服务的 ClickHouse Cloud API key
为 Cloud 启用远程 MCP 服务器
连接到要为其启用远程 MCP 服务器的 ClickHouse Cloud 服务。 在左侧菜单中,点击 Connect。此时会打开一个显示连接详情的对话框。 选择 Connect with MCP:
control-plane:service:manage-mcp 权限 (参见控制台角色和权限) :

在无头环境中进行身份验证
如果您的 MCP 客户端运行在远程主机或无头主机上,不便使用基于浏览器的 OAuth 流程,请改用 ClickHouse Cloud API key 进行身份验证。- 在 ClickHouse Cloud 控制台中,打开您的组织并选择 API Keys。
-
创建一个 key,仅授予 MCP 客户端访问相关组织和服务所需的最小角色和权限,然后下载 key ID 和 secret。
如需改用
clickhousectl创建 key,请先查找角色 ID,然后创建 key,并为 MCP 主机配置 IP 允许列表。clickhousectl需要一个已有的、具备创建 key 权限的 API key:该命令只会输出一次新 key 的 ID 和 secret,请将其妥善保存到您的机密信息管理系统中。如果未指定--ip-allow,该 key 的 IP 允许列表将为空,所有访问都会被拒绝。 - 在远程主机上,通过您的机密信息管理系统提供这些凭证,并生成 HTTP Basic 授权值:
- 选择您的 MCP 客户端,并添加远程 MCP 服务器:
- Claude Code
- Codex
- OpenCode
CH_AUTH。启动 Claude Code 并运行 /mcp,确认 clickhouse-cloud 已连接。有关远程 HTTP 服务器和请求头配置的详细信息,请参阅 Claude Code MCP 文档。CH_AUTH 在每个客户端会话中均可用,切勿将 API key、机密信息或 CH_AUTH 的值提交到源代码管理系统。Base64 编码并不会对凭证进行加密。
使用这种 API key 方式,既不需要浏览器,也无需另行通过 clickhousectl 登录。如果您在同一主机上也使用 clickhousectl,它会读取相同的 CLICKHOUSE_CLOUD_API_KEY 和 CLICKHOUSE_CLOUD_API_SECRET 变量,且这些变量的优先级高于浏览器登录。
在工作目录中,运行以下命令,将 ClickHouse Cloud MCP Server 配置添加到 Claude Code 中:
clickhouse-cloud,然后使用 ClickHouse Cloud 凭据通过 OAuth 完成身份验证。
- 前往 Customize > Connectors
- 点击 “+” 图标,然后点击 Add custom connector
- 为自定义连接器命名,例如
clickhouse-cloud,然后将其添加 - 点击新添加的
clickhouse-cloud连接器,然后点击 Connect - 通过 OAuth 使用你的 ClickHouse Cloud 凭据进行身份验证
- 在 Cursor 市场中浏览并安装 MCP 服务器。
- 搜索 ClickHouse,然后在任一服务器上点击“Add to Cursor”进行安装
- 通过 OAuth 进行身份验证。
.vscode/mcp.json 中:
mcp_config.json 文件:
用自然语言提问,agent 会将其转换为 SQL:
run_select_query 工具只允许执行 SELECT 语句。所有查询均为只读。
查看你的 ClickHouse Cloud 资源信息: