ClickHouse Cloud MCP 工具（用于 ADK）

Supported in ADKPythonTypeScript

ClickHouse Cloud 远程 MCP 服务器可将 ADK 智能体直接连接到你的 ClickHouse Cloud 服务。你的智能体可以列出数据库和表、检查 schema、运行只读 SQL 查询，以及查看服务、备份、ClickPipes、计费等信息，并访问许多其他工具。

该服务器完全托管，无需本地安装、Docker 容器或 API 密钥配置。认证使用 OAuth 2.0，访问范围限定为已认证用户有权访问的组织和服务。

使用场景

• 探索和分析数据：发现数据库和表，检查列定义，并以自然语言运行分析型 SELECT 查询。问出「过去 7 天内按国家/地区统计的平均会话时长是多少？」这样的问题，让智能体将其转换为 SQL。
• 生成洞察和报告：将分析结果提取为摘要、可视化图表或下游工作流，无需构建自定义数据流水线。
• 监控基础设施：列出组织中的服务，检查服务状态和详情，查看备份计划和最近的备份，以及检查已配置的 ClickPipes。
• 跟踪成本：检索组织的计费和使用数据，包括按日期范围内的每日每实体成本记录。

前提条件

• 运行中的 ClickHouse 实例（ClickHouse Cloud 或自托管）
• 本地 MCP 服务器：已安装 uv（用于运行 mcp-clickhouse 的 uvx），以及一个具有智能体所需最低权限的 ClickHouse 用户
• 远程 MCP 服务器（仅限 ClickHouse Cloud）：为服务启用远程 MCP 服务器。在 ClickHouse Cloud 控制台中，打开你的服务，点击 Connect，选择 Connect with MCP，然后将其打开

在智能体中使用

PythonTypeScript

本地 MCP 服务器远程 MCP 服务器

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

clickhouse_tools = McpToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="uvx",
            args=["mcp-clickhouse"],
            env={
                "CLICKHOUSE_HOST": "<your-instance>.clickhouse.cloud",
                "CLICKHOUSE_USER": "<clickhouse-user>",
                "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
                "CLICKHOUSE_PORT": "8443",
            },
        ),
        timeout=60,
    )
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="clickhouse_agent",
    instruction="Help users explore and analyze data in ClickHouse. "
    "Use the ClickHouse tools to query the data before answering. "
    "Always ground your answer in actual query results, not assumptions.",
    tools=[clickhouse_tools],
)

将 CLICKHOUSE_HOST 替换为你的实例主机名（适用于 ClickHouse Cloud 或自托管）。使用仅具有智能体所需权限的专用数据库用户。避免使用 default 或管理员用户。查询默认以只读方式运行。

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

root_agent = Agent(
    model="gemini-flash-latest",
    name="clickhouse_agent",
    instruction="Help users explore and analyze data in ClickHouse Cloud",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mcp.clickhouse.cloud/mcp",
            ),
        )
    ],
)

远程 MCP 服务器

import { LlmAgent, MCPToolset } from "@google/adk";

const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "clickhouse_agent",
    instruction: "Help users explore and analyze data in ClickHouse Cloud",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mcp.clickhouse.cloud/mcp",
        }),
    ],
});

export { rootAgent };

注意

使用远程 MCP 服务器时，智能体首次连接时会提示你在浏览器中使用 ClickHouse Cloud 凭据授权连接。访问范围限定为你的用户有权访问的组织和服务。而本地 MCP 服务器则使用其环境变量中的数据库凭据进行认证，无需 OAuth 流程。

安全性

远程 MCP 服务器暴露的所有工具都是只读的。每个工具在其 MCP 元数据中都标注了 readOnlyHint: true。任何工具都无法修改数据、更改服务配置或执行任何破坏性操作。run_select_query 工具仅允许 SELECT 语句。

本地 MCP 服务器默认也是只读的。写入访问需要显式设置 CLICKHOUSE_ALLOW_WRITE_ACCESS=true，破坏性操作（DROP、TRUNCATE）还需要额外设置 CLICKHOUSE_ALLOW_DROP=true。

可用工具

本地 MCP 服务器

工具	描述
run_query	执行 SQL 查询（默认只读）
list_databases	列出 ClickHouse 实例上的所有数据库
list_tables	列出数据库中的表，支持分页和可选的 like/not_like 过滤器

远程 MCP 服务器（ClickHouse Cloud）

远程服务器暴露以下类别的只读工具。

查询和 schema 探索

工具	描述
run_select_query	对 ClickHouse 服务执行只读 SELECT 查询
list_databases	列出 ClickHouse 服务中所有可用的数据库
list_tables	列出数据库中的所有表，包括列定义，支持可选的 like/notLike 过滤器

组织

工具	描述
get_organizations	检索已认证用户可访问的所有 ClickHouse Cloud 组织
get_organization_details	返回单个组织的详情

服务

工具	描述
get_services_list	列出 ClickHouse Cloud 组织中的所有服务
get_service_details	返回特定服务的详情

备份

工具	描述
list_service_backups	列出服务的所有备份，按最近优先排序
get_service_backup_details	返回单个备份的详情
get_service_backup_configuration	返回服务的备份配置（计划和保留设置）

ClickPipes

工具	描述
list_clickpipes	列出服务中配置的所有 ClickPipes
get_clickpipe	返回特定 ClickPipe 的详情

计费

工具	描述
get_organization_cost	检索组织的计费和使用成本数据，支持可选的 from_date/to_date（最大 31 天范围）

选择本地还是远程

	本地 MCP 服务器	远程 MCP 服务器
来源	mcp-clickhouse（开源）	由 ClickHouse Cloud 完全托管
传输方式	通过 uvx 的本地 stdio	可流式 HTTP（https://mcp.clickhouse.cloud/mcp）
适用范围	任何 ClickHouse 实例（自托管或 Cloud）	仅限 ClickHouse Cloud 服务
认证方式	环境变量（数据库用户）	OAuth 2.0（Cloud 凭据）
工具	3 个工具：查询和 schema 探索	多个工具：查询、schema 探索、服务管理、备份、ClickPipes、计费

更多资源

• mcp-clickhouse（GitHub）
• ClickHouse Cloud 远程 MCP 文档
• 远程 MCP 设置指南
• ClickHouse Cloud