如何使用 ClickHouse MCP Server 构建 LlamaIndex AI Agent

在本指南中，你将学习如何构建一个 LlamaIndex AI Agent，使其能够通过 ClickHouse 的 MCP Server 与 ClickHouse 的 SQL playground 进行交互。

示例 Notebook

该示例可以在 examples 仓库中以 Notebook 形式查看。

前置条件

您需要在系统上安装 Python。
您需要在系统上安装 pip。
您需要 Anthropic API 密钥或其他 LLM 提供商的 API 密钥。

您可以通过 Python REPL 或脚本运行以下步骤。

安装依赖库

运行以下命令来安装所需的依赖库：

pip install -q --upgrade pip
pip install -q llama-index clickhouse-connect llama-index-llms-anthropic llama-index-tools-mcp

设置凭据

接下来，您需要提供 Anthropic API 密钥：

import os, getpass
os.environ["ANTHROPIC_API_KEY"] = getpass.getpass("Enter Anthropic API Key:")

输入 Anthropic API 密钥：········

使用其他 LLM 提供商

如果你没有 Anthropic API 密钥，并且想要使用其他 LLM 提供商，可以在 LlamaIndex「LLMs」文档中找到配置凭据的说明。

初始化 MCP Server

现在将 ClickHouse MCP Server 配置为指向 ClickHouse SQL playground。你需要将这些 Python 函数转换为 LlamaIndex 工具：

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

mcp_client = BasicMCPClient(
    "uv",
    args=[
        "run",
        "--with", "mcp-clickhouse",
        "--python", "3.13",
        "mcp-clickhouse"
    ],
    env={
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true"
    }
)

mcp_tool_spec = McpToolSpec(
    client=mcp_client,
)

tools = await mcp_tool_spec.to_tool_list_async()

## 创建代理 \{#create-agent}

现在可以创建一个能够访问这些工具的代理。将单次运行中工具调用的最大次数设置为 10。如需要,可以修改此参数:

```python
from llama_index.core.agent import AgentRunner, FunctionCallingAgentWorker

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

初始化 LLM

使用以下代码初始化 Claude Sonnet 4.0 模型：

from llama_index.llms.anthropic import Anthropic
llm = Anthropic(model="claude-sonnet-4-0")

运行代理

最后,您可以向代理提问:

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

返回的响应内容较长,因此在下面的示例响应中已被截断:

Added user message to memory: What's the most popular repository?
=== LLM Response ===
I'll help you find the most popular repository. Let me first explore the available databases and tables to understand the data structure.
=== Calling Function ===
Calling function: list_databases with args: {}
=== Function Output ===
meta=None content=[TextContent(type='text', text='amazon\nbluesky\ncountry\ncovid\ndefault\ndns\nenvironmental\nfood\nforex\ngeo\ngit\ngithub\nhackernews\nimdb\nlogs\nmetrica\nmgbench\nmta\nnoaa\nnyc_taxi\nnypd\nontime\nopensky\notel\notel_v2\npypi\nrandom\nreddit\nrubygems\nstackoverflow\nstar_schema\nstock\nsystem\ntw_weather\ntwitter\nuk\nwiki\nwords\nyoutube', annotations=None)] isError=False
=== LLM Response ===
I can see there's a `github` database which likely contains repository data. Let me explore the tables in that database.
=== Calling Function ===
Calling function: list_tables with args: {"database": "github"}
=== Function Output ===
...
...
...
=== LLM Response ===
Based on the GitHub data, **the most popular repository is `sindresorhus/awesome`** with **402,292 stars**.

Here are the top 10 most popular repositories by star count:

1. **sindresorhus/awesome** - 402,292 stars
2. **996icu/996.ICU** - 388,413 stars
3. **kamranahmedse/developer-roadmap** - 349,097 stars
4. **donnemartin/system-design-primer** - 316,524 stars
5. **jwasham/coding-interview-university** - 313,767 stars
6. **public-apis/public-apis** - 307,227 stars
7. **EbookFoundation/free-programming-books** - 298,890 stars
8. **facebook/react** - 286,034 stars
9. **vinta/awesome-python** - 269,320 stars
10. **freeCodeCamp/freeCodeCamp** - 261,824 stars

The `sindresorhus/awesome` repository is a curated list of awesome lists, which explains its popularity as it serves as a comprehensive directory of resources across many different topics in software development.

前置条件​

安装依赖库​

设置凭据​

初始化 MCP Server​

初始化 LLM​

运行代理​