启用并连接 ClickHouse Cloud 远程 MCP 服务器

本指南介绍如何启用 ClickHouse Cloud Remote MCP 服务器，并将其配置为可与常见的开发者工具配合使用。 前置条件

一个正在运行的 ClickHouse Cloud 服务
你选择的 IDE 或智能体开发工具
如需进行无头 (headless) 身份验证，还需要一个有权访问所需组织和服务的 ClickHouse Cloud API key

为 Cloud 启用远程 MCP 服务器

连接到要为其启用远程 MCP 服务器的 ClickHouse Cloud 服务。在左侧菜单中，点击 Connect。此时会打开一个显示连接详情的对话框。选择 Connect with MCP：打开切换开关，为该服务启用 MCP。启用或禁用 MCP 需要具备 control-plane:service:manage-mcp 权限 (参见控制台角色和权限) ：复制显示的 URL，它与下方的 URL 相同：

https://mcp.clickhouse.cloud/mcp

为开发配置远程 MCP

请选择下方的 IDE 或工具，并按相应说明完成设置。

在无头环境中进行身份验证

如果您的 MCP 客户端运行在远程主机或无头主机上，不便使用基于浏览器的 OAuth 流程，请改用 ClickHouse Cloud API key 进行身份验证。

在 ClickHouse Cloud 控制台中，打开您的组织并选择 API Keys。
创建一个 key，仅授予 MCP 客户端访问相关组织和服务所需的最小角色和权限，然后下载 key ID 和 secret。
在远程主机上，通过您的机密信息管理系统提供这些凭证，并生成 HTTP Basic 授权值：

export CLICKHOUSE_CLOUD_API_KEY="<key_id>"
export CLICKHOUSE_CLOUD_API_SECRET="<key_secret>"

export CH_AUTH="Basic $(
  printf '%s:%s' \
    "$CLICKHOUSE_CLOUD_API_KEY" \
    "$CLICKHOUSE_CLOUD_API_SECRET" |
  base64 | tr -d '\n'
)"

选择您的 MCP 客户端,并添加远程 MCP 服务器:

Claude Code
Codex
OpenCode

claude mcp add \
  --scope user \
  --transport http \
  clickhouse-cloud \
  https://mcp.clickhouse.cloud/mcp \
  --header 'Authorization: ${CH_AUTH}'

Claude Code 在建立连接时会从环境变量中展开 CH_AUTH。启动 Claude Code 并运行 /mcp,确认 clickhouse-cloud 已连接。有关远程 HTTP 服务器和请求头配置的详细信息,请参阅 Claude Code MCP 文档。

在 ~/.codex/config.toml 中添加以下条目:

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"
env_http_headers = { Authorization = "CH_AUTH" }

运行 codex mcp list,确认 clickhouse-cloud 已完成配置。有关 mcp_servers.<id>.env_http_headers 的详细信息,请参阅 Codex 配置参考文档。

在您的 opencode.jsonc 配置中添加以下条目:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse-cloud": {
        "type": "remote",
        "url": "https://mcp.clickhouse.cloud/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "{env:CH_AUTH}"
        }
      }
    }
  }
}

运行 opencode mcp list,确认 clickhouse-cloud 已连接。有关远程服务器、请求头以及环境变量替换的详细信息,请参阅 OpenCode MCP 文档。

请确保 CH_AUTH 在每个客户端会话中均可用,切勿将 API key、机密信息或 CH_AUTH 的值提交到源代码管理系统。Base64 编码并不会对凭证进行加密。使用这种 API key 方式,既不需要浏览器,也无需另行通过 clickhousectl 登录。

Claude Code

在工作目录中，运行以下命令，将 ClickHouse Cloud MCP Server 配置添加到 Claude Code 中：

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

然后启动 Claude Code：

claude

运行以下命令以列出 MCP 服务器：

/mcp

选择 clickhouse-cloud，然后使用 ClickHouse Cloud 凭据通过 OAuth 完成身份验证。

Claude web UI

前往 Customize > Connectors
点击 “+” 图标，然后点击 Add custom connector
为自定义连接器命名，例如 clickhouse-cloud，然后将其添加
点击新添加的 clickhouse-cloud 连接器，然后点击 Connect
通过 OAuth 使用你的 ClickHouse Cloud 凭据进行身份验证

Cursor

在 Cursor 市场中浏览并安装 MCP 服务器。
搜索 ClickHouse，然后在任一服务器上点击“Add to Cursor”进行安装
通过 OAuth 进行身份验证。

Visual Studio Code

将以下配置添加到 .vscode/mcp.json 中：

{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

更多详情请参阅 Visual Studio Code 文档。

Windsurf

按以下配置编辑 mcp_config.json 文件：

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

更多详细信息请参阅 Windsurf 文档。

Zed

将 ClickHouse 添加为自定义服务器。在 Zed 设置的 context_servers 下添加以下内容：

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

当 Zed 首次连接到服务器时，应会提示你通过 OAuth 进行身份验证。更多信息请参阅 Zed 文档。

Codex

运行以下命令，通过 CLI 添加 ClickHouse Cloud MCP 服务器：

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

示例用法

连接完成后，您就可以通过自然语言提示词与 ClickHouse Cloud 交互。下面列出了一些常见工作流，以及您的 MCP 客户端会在后台调用的工具。如需查看可用工具的完整列表，请参阅工具参考。

探索你的数据

先查看有哪些可用内容：

提示词	调用的工具
”我可以访问哪些组织？“	`get_organizations`
”我的服务中有哪些可用数据库？“	`list_databases`
”显示 `default` 数据库中的表”	`list_tables`
”列出所有名称以 `events_` 开头的表”	`list_tables` (使用 `like` 过滤器)

执行分析查询

用自然语言提问，agent 会将其转换为 SQL：

提示词	调用的工具
“显示 `hits` 表中的前 10 行”	`run_select_query`
“过去 7 天按国家分组的平均 session 耗时是多少？”	`run_select_query`
“`analytics` 数据库中的每个表各有多少行？”	`run_select_query`

run_select_query 工具只允许执行 SELECT 语句。所有查询均为只读。

管理服务和基础设施

查看你的 ClickHouse Cloud 资源信息：

提示词	调用的工具
”列出我所有的服务”	`get_services_list`
”我的生产服务当前状态如何？“	`get_service_details`
”显示此服务的备份计划”	`get_service_backup_configuration`
”列出最近的备份”	`list_service_backups`
”此服务上配置了哪些 ClickPipes？“	`list_clickpipes`

监控成本

提示词	调用的工具
“我的组织上周的成本是多少？”	`get_organization_cost`
“显示 3 月 1 日至 3 月 15 日的每日成本”	`get_organization_cost` (使用 `from_date` 和 `to_date`)

ClickHouse agent 技能

入门

服务与基础设施

自备 Cloud

数据与集成

连接与查询

访问管理

安全与合规

监控与备份

AI 工具与智能体

Cloud API

账单

支持

ClickHouse Private

启用并连接 ClickHouse Cloud 远程 MCP 服务器

为 Cloud 启用远程 MCP 服务器

为开发配置远程 MCP

在无头环境中进行身份验证

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

示例用法

探索你的数据

执行分析查询

管理服务和基础设施

监控成本

​为 Cloud 启用远程 MCP 服务器

​为开发配置远程 MCP

​在无头环境中进行身份验证

​Claude Code

​Claude web UI

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​示例用法

​探索你的数据

​执行分析查询

​管理服务和基础设施

​监控成本

​相关内容

为 Cloud 启用远程 MCP 服务器

为开发配置远程 MCP

在无头环境中进行身份验证

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

示例用法

探索你的数据

执行分析查询

管理服务和基础设施

监控成本

相关内容