与 ClickHouse MCP 的集成：打造面向智能体的高效数据体验

最新推荐文章于 2025-06-27 18:31:23 发布

原创最新推荐文章于 2025-06-27 18:31:23 发布 · 932 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#microsoft

软件工程专栏收录该内容

91 篇文章

订阅专栏

本文字数：6547；估计阅读时间：17 分钟

作者：ClickHouse Team

本文在公众号【ClickHouseInc】首发

MCP（Model Connected Protocol）是一种新兴协议，用于将数据库、API、工具等第三方服务接入大语言模型（LLM）体系。通过部署 MCP 服务器，可以定义客户端如何与您的服务交互。MCP 客户端（如 Claude Desktop、ChatGPT、Cursor、Windsurf 等）连接到该服务器后，就能让 LLM 与这些服务进行实时交互。随着 MCP 快速成为行业默认标准，我们也在今年早些时候发布了 ClickHouse 的官方 MCP 服务器：mcp-clickhouse [https://github.com/ClickHouse/mcp-clickhouse]。

自然语言接口正在几乎所有领域快速普及，ClickHouse 的用户群体也不例外。无论是软件工程师、数据工程师还是分析工程师，大家都在开始使用自然语言和智能体式（agentic）界面来完成部分日常任务。无论你是否精通 SQL，如今都可以通过这种新方式更轻松地与数据交互。我们正看到一个趋势：LLM 正在帮助每个人扩展自己的技能边界 —— 软件工程师能处理更多数据任务，数据工程师能更深入参与开发流程。数据，正以前所未有的方式被更广泛地使用。

在所有这些新型用户体验中，“快速响应”与“流畅交互”成为核心诉求。用户不再是周五下午发出查询，顺道买份 Bánh mì，然后等到周一再来看结果。他们与 LLM 进行的是实时对话式交互，响应必须在数秒内完成，并且支持连续提问与迭代。这个过程中如果引入第三方服务，它们必须跟得上这种交互节奏。如果用户希望通过自然语言与数据库对话，那么底层系统就必须具备这种响应能力。

这正是 ClickHouse 成为智能体驱动数据工作流理想数据库的原因所在。ClickHouse 天生就是为极致性能而设计的分析型数据库 —— 不浪费一丝存储空间、不浪费一毫秒执行时间。甚至在 LLM 与智能体时代到来之前，ClickHouse 就已经在支持大规模交互式分析方面走在前列。我们从未刻意追求成为 Agentic AI 的标配数据库，但有时候，美好的结果就是这么“刚刚好”。

未来的使用场景

尽管智能体接口正快速流行，但整个生态仍处于早期阶段，相关工具、工作流和应用方式都在迅速演进中。我们看到，越来越多用户开始跳过传统的 SQL 查询界面和 BI 工具，直接通过 Claude Desktop、ChatGPT 等自然语言界面与数据交互，不写 SQL 就能生成分析结果和可视化图表。同时，我们也注意到，许多没有数据背景的开发者正在构建面向终端用户的数据产品，借助大语言模型不仅实现前端生成，还能辅助数据建模与查询优化，应对高并发访问需求。

随着 ClickHouse 成为 Observability 2.0 的首选平台，越来越多的 SRE 和 DevOps 团队也开始借助 LLM 查询日志、指标和链路追踪数据。他们无需掌握复杂的查询语法，就能实现全文搜索与数据分析的融合体验。

更进一步地，我们也在构想下一个可能场景：未来的大语言模型，或许可以自动读取可观测性数据，自主生成架构优化建议、性能调优方案甚至 bug 修复建议 —— 用户无需明确提示具体错误，LLM 就能主动感知系统变化并给出反馈。

为了让这一切更加易用，ClickHouse Cloud 即将上线远程 MCP 服务器，作为默认的智能体交互接口。这意味着所有 MCP 客户端都可以直接接入你的云端实例，无需额外本地配置。

想第一时间试用这些 AI 功能？欢迎访问 clickhouse.ai，注册内测候补名单[https://clickhouse.com/ai]。

ClickHouse MCP 智能体示例

为了帮助开发者快速上手，我们准备了一系列集成示例，展示如何将主流库与 ClickHouse MCP 服务器对接。

这些示例基于开源的 mcp-clickhouse 服务器即可运行。如果你想了解它在更宏观 AI 架构中的定位，也可以查看我们的 AgentHouse 演示[https://clickhouse.com/blog/agenthouse-demo-clickhouse-llm-mcp]，以及我们对“面向 Agent 的分析”方式的一些探索与思考[https://clickhouse.com/blog/agent-facing-analytics]。

全部五个示例可在 ClickHouse/examples 仓库中获取[https://github.com/ClickHouse/examples/tree/main/ai/mcp]。它们默认连接至 ClickHouse SQL Playground [https://sql.clickhouse.com/]，你可以根据以下配置快速部署并运行。

env = {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true"
}

在示例中我们也使用了 Anthropic 的模型，并通过 ANTHROPIC_API_KEY 环境变量设置访问凭证。

1. Agno 示例

我们从 Agno（原名 PhiData）开始说起 —— 它是一个轻量级、高性能的 AI 智能体开发库。

async with MCPTools(command="uv run --with mcp-clickhouse --python 3.13 mcp-clickhouse", env=env, timeout_seconds=60) as mcp_tools:
    agent = Agent(
        model=Claude(id="claude-3-5-sonnet-20240620"),
        markdown=True, 
        tools = [mcp_tools]
    )
    await agent.aprint_response("What's the most starred project in 2025?", stream=True)

使用 Agno 的 API 十分简洁。我们只需通过命令启动本地 MCP 服务器并初始化 MCPTools 工具集，所有工具会自动注册至 mcp_tools 变量。接下来只需将这些工具传入智能体并调用，即可完成交互流程。

查看完整 Agno 示例[https://github.com/ClickHouse/examples/tree/main/ai/mcp/agno]。

2. DSPy

DSPy用于语言模型编程的斯坦福框架。

server_parameters = StdioServerParameters(
    command="uv",
    args=[
        'run',
        '--with', 'mcp-clickhouse',
        '--python', '3.13',
        'mcp-clickhouse'
    ],
    env=env
)

dspy.configure(lm=dspy.LM("anthropic/claude-sonnet-4-20250514"))

class DataAnalyst(dspy.Signature):
    """You are a data analyst. You'll be asked questions and you need to try to answer them using the tools you have access to. """

    user_request: str = dspy.InputField()
    process_result: str = dspy.OutputField(
        desc=(
            "Answer to the query"
        )
    )

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

        dspy_tools = []
        for tool in tools.tools:
            dspy_tools.append(dspy.Tool.from_mcp_tool(session, tool))

        print("Tools", dspy_tools)

        react = dspy.ReAct(DataAnalyst, tools=dspy_tools)
        result = await react.acall(user_request="What's the most popular Amazon product category")
        print(result)

相比其他框架，DSPy 的集成稍显复杂。我们同样需要初始化 MCP 服务器，但与其他框架直接传入命令字符串不同，DSPy 要求将启动命令和参数分别传入。

此外，DSPy 要求每次交互都定义一个 Signature 类，其中明确列出输入字段和输出字段。这个 Signature 类在智能体构建时作为参数传入，并通过 DSPy 提供的 React 类进行智能体初始化。

所谓 React，即“推理与执行” —— 它让 LLM 判断是否需要调用某个工具，或者直接结束对话流程；一旦需要调用工具，模型将决定使用哪个工具，并自动生成所需参数。

在集成过程中，我们需要遍历 MCP 工具列表，并将其转换为 DSPy 所支持的格式。

查看完整 DSPy 示例[https://github.com/ClickHouse/examples/tree/main/ai/mcp/dspy]

3. LangChain

LangChain构建 LLM 应用的开发框架。

server_params = StdioServerParameters(
    command="uv", 
    args=[
        "run", 
        "--with", "mcp-clickhouse",
        "--python", "3.13", 
        "mcp-clickhouse"
    ],
    env=env
)
         
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await load_mcp_tools(session)
        agent = create_react_agent("anthropic:claude-sonnet-4-0", tools)
        
        handler = UltraCleanStreamHandler()        
        async for chunk in agent.astream_events(
            {"messages": [{"role": "user", "content": "Who's committed the most code to ClickHouse?"}]}, 
            version="v1"
        ):
            handler.handle_chunk(chunk)
            
        print("\n")

LangChain 的接入方式与 DSPy 类似：初始化 MCP 服务器，调用 ReAct 函数创建智能体，并传入 MCP 工具集合。为了让输出更清晰易读，我们（其实是 Claude！）还写了一段自定义渲染逻辑 UltaCleanStreamHandler，用于格式化返回内容。

查看完整 LangChain 示例[https://github.com/ClickHouse/examples/tree/main/ai/mcp/langchain]

4. LlamaIndex

LlamaIndex为 LLM 构建的数据框架。

mcp_client = BasicMCPClient(
    "uv", 
    args=[
        "run", 
        "--with", "mcp-clickhouse",
        "--python", "3.13", 
        "mcp-clickhouse"
    ],
    env=env
)

mcp_tool_spec = McpToolSpec(
    client=mcp_client,
)

tools = await mcp_tool_spec.to_tool_list_async()

agent_worker = FunctionCallingAgentWorker.from_tools(
    tools=tools, 
    llm=llm, verbose=True, max_function_calls=10
)
agent = AgentRunner(agent_worker)

response = agent.query("What's the most popular repository?")

LlamaIndex 同样遵循标准流程：先初始化 MCP 服务端，再将工具和 LLM 一起初始化为智能体。在实际测试中，我们发现默认的 max_function_calls 设置为 5 次时不足以完成一次完整交互，因此手动将其提升至 10 次以获得更好的效果。

查看完整 LlamaIndex 示例[https://github.com/ClickHouse/examples/tree/main/ai/mcp/llamaindex]

5. PydanticAI

PydanticAI面向生产环境的 Python 智能体框架。

server = MCPServerStdio(  
    'uv',
    args=[
        'run',
        '--with', 'mcp-clickhouse',
        '--python', '3.13',
        'mcp-clickhouse'
    ],
    env=env
)
agent = Agent('anthropic:claude-sonnet-4-0', mcp_servers=[server])

async with agent.run_mcp_servers():
    result = await agent.run("Who's done the most PRs for ClickHouse?")
    print(result.output)

PydanticAI 提供了最简洁的 API 设计。我们只需初始化 MCP 服务器并将其传入智能体对象。框架会以异步上下文管理器方式运行服务，用户只需在该上下文中发出请求，即可与智能体进行对话。

查看完整 PydanticAI 示例[https://github.com/ClickHouse/examples/tree/main/ai/mcp/pydanticai]

欢迎体验：MCP + ClickHouse 的无限可能

我们对 MCP 与 ClickHouse 的集成探索才刚刚开始，特别期待听到你在项目中如何使用 mcp-clickhouse，也欢迎分享你的实践经验。

立即试用以上集成示例，动手构建属于你的智能体应用吧！如果你遇到任何问题，或者有功能建议，欢迎通过 GitHub 提交 issue，或在 Slack 社区与我们直接交流[https://clickhousedb.slack.com/join/shared_invite/zt-2nvsplppi-I7FnTTjR9zCLAbOZnyqb4g#/shared-invite/email]。