如何使用 CrewAI 和 ClickHouse MCP Server 构建 AI 代理

在本指南中，您将学习如何构建一个使用 ClickHouse MCP Server 与 ClickHouse SQL playground 进行交互的 mcp-agent AI 代理。

示例笔记本

该示例可以在 examples 仓库中找到对应的示例笔记本。

前提条件

需要在系统上安装 Python。
需要在系统上安装 pip。
需要一个 OpenAI API 密钥。

你可以在 Python REPL 中或使用脚本运行以下步骤。

安装依赖库

运行以下命令安装 mcp-agent 库:

pip install -q --upgrade pip
pip install -q mcp-agent openai
pip install -q ipywidgets

设置凭据

接下来,您需要提供 OpenAI API 密钥:

import os, getpass
os.environ["OPENAI_API_KEY"] = getpass.getpass("输入 OpenAI API 密钥：")

输入 OpenAI API 密钥:········

接下来,定义连接到 ClickHouse SQL playground 所需的凭据:

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

初始化 MCP Server 和 mcp-agent 代理

现在配置 ClickHouse MCP Server 指向 ClickHouse SQL playground，然后初始化代理并向其提问：

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
from mcp_agent.config import Settings, MCPSettings, MCPServerSettings, OpenAISettings

settings = Settings(
    execution_engine="asyncio",
    openai=OpenAISettings(
        default_model="gpt-5-mini-2025-08-07",
    ),
    mcp=MCPSettings(
        servers={
            "clickhouse": MCPServerSettings(
                command='uv',
                args=[
                    "run",
                    "--with", "mcp-clickhouse",
                    "--python", "3.10",
                    "mcp-clickhouse"
                ],
                env=env
            ),
        }
    ),
)

app = MCPApp(name="mcp_basic_agent", settings=settings)

async with app.run() as mcp_agent_app:
    logger = mcp_agent_app.logger
    data_agent = Agent(
        name="database-anayst",
        instruction="""您可以借助 ClickHouse 数据库回答问题。""",
        server_names=["clickhouse"],
    )

    async with data_agent:
        llm = await data_agent.attach_llm(OpenAIAugmentedLLM)
        result = await llm.generate_str(
            message="请告诉我 2025 年英国房产价格的情况。使用 ClickHouse 进行计算。"
        )
        
        logger.info(result)

[10/10/25 11:26:20] INFO     正在启动 MCP 服务器 'mcp-clickhouse',传输方式为 'stdio'                                      server.py:1502
2025-10-10 11:26:20,183 - mcp.server.lowlevel.server - INFO - 正在处理类型为 ListToolsRequest 的请求
2025-10-10 11:26:20,184 - mcp.server.lowlevel.server - INFO - 正在处理类型为 ListPromptsRequest 的请求
2025-10-10 11:26:20,185 - mcp.server.lowlevel.server - INFO - 正在处理类型为 ListResourcesRequest 的请求
[INFO] 2025-10-10T11:26:20 mcp_agent.workflows.llm.augmented_llm_openai.database-anayst - 使用推理模型 'gpt-5-mini-2025-08-07',推理强度为 'medium'
[INFO] 2025-10-10T11:26:23 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "list_databases",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
2025-10-10 11:26:23,477 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - 正在列出所有数据库
2025-10-10 11:26:23,479 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户为 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:24,375 - mcp-clickhouse - INFO - 已成功连接到 ClickHouse 服务器版本 25.8.1.8344
2025-10-10 11:26:24,551 - mcp-clickhouse - INFO - 找到 38 个数据库
[INFO] 2025-10-10T11:26:26 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "list_tables",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
2025-10-10 11:26:26,825 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - 正在列出数据库 'uk' 中的表
2025-10-10 11:26:26,832 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户为 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:27,311 - mcp-clickhouse - INFO - 已成功连接到 ClickHouse 服务器版本 25.8.1.8344
2025-10-10 11:26:28,738 - mcp-clickhouse - INFO - 找到 9 个表
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "run_select_query",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "run_select_query",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "run_select_query",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "run_select_query",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
[INFO] 2025-10-10T11:26:48 mcp_agent.mcp.mcp_aggregator.database-anayst - 正在请求工具调用
{
  "data": {
    "progress_action": "调用工具",
    "tool_name": "run_select_query",
    "server_name": "clickhouse",
    "agent_name": "database-anayst"
  }
}
2025-10-10 11:26:48,366 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - 正在执行 SELECT 查询: SELECT
count(*) AS transactions,
avg(price) AS avg_price,
quantileExact(0.5)(price) AS median_price,
min(price) AS min_price,
max(price) AS max_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
2025-10-10 11:26:48,367 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户为 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:49,262 - mcp-clickhouse - INFO - 已成功连接到 ClickHouse 服务器版本 25.8.1.8344
2025-10-10 11:26:49,407 - mcp-clickhouse - INFO - 查询返回 1 行
2025-10-10 11:26:49,408 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - 正在执行 SELECT 查询: SELECT toMonth(date) AS month, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
GROUP BY month
ORDER BY month
2025-10-10 11:26:49,408 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户为 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:49,857 - mcp-clickhouse - INFO - 已成功连接到 ClickHouse 服务器版本 25.8.1.8344
2025-10-10 11:26:50,067 - mcp-clickhouse - INFO - 查询返回 8 行
2025-10-10 11:26:50,068 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - 正在执行 SELECT 查询: SELECT town, count(*) AS transactions, avg(price) AS avg_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date)=2025
GROUP BY town
HAVING transactions >= 50
ORDER BY avg_price DESC
LIMIT 10
2025-10-10 11:26:50,069 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户为 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:50,594 - mcp-clickhouse - INFO - 已成功连接到 ClickHouse 服务器版本 25.8.1.8344
2025-10-10 11:26:50,741 - mcp-clickhouse - INFO - 查询返回 10 行
2025-10-10 11:26:50,744 - mcp.server.lowlevel.server - INFO - 正在处理类型为 CallToolRequest 的请求
2025-10-10 11:26:50,746 - mcp-clickhouse - INFO - 正在执行 SELECT 查询: SELECT toYear(date) AS year, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid_simple_partitioned
WHERE toYear(date) IN (2024,2025)
GROUP BY year
ORDER BY year
2025-10-10 11:26:50,747 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:51,256 - mcp-clickhouse - INFO - 已成功连接至 ClickHouse 服务器,版本 25.8.1.8344
2025-10-10 11:26:51,447 - mcp-clickhouse - INFO - 查询返回 2 行
2025-10-10 11:26:51,449 - mcp.server.lowlevel.server - INFO - 正在处理 CallToolRequest 类型请求
2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - 正在执行 SELECT 查询: SELECT type, count(*) AS transactions, avg(price) AS avg_price, quantileExact(0.5)(price) AS median_price
FROM uk.uk_price_paid
WHERE toYear(date)=2025
GROUP BY type
ORDER BY avg_price DESC
2025-10-10 11:26:51,452 - mcp-clickhouse - INFO - 正在创建 ClickHouse 客户端连接至 sql-clickhouse.clickhouse.com:8443,用户 demo (secure=True, verify=True, connect_timeout=30s, send_receive_timeout=30s)
2025-10-10 11:26:51,952 - mcp-clickhouse - INFO - 已成功连接至 ClickHouse 服务器,版本 25.8.1.8344
2025-10-10 11:26:52,166 - mcp-clickhouse - INFO - 查询返回 5 行
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp_basic_agent - 摘要 (TL;DR)
- 基于 ClickHouse 中的英国房价支付表,2025 年至今记录的交易共有 376,633 笔销售,平均价格为 £362,283,中位数价格为 £281,000。数据似乎仅包含 2025 年 1 月至 8 月(因此 2025 年数据不完整)。存在极端异常值(最小值 £100,最大值 £127,700,000),使平均值出现偏差。

我的计算内容(方法)
我在 ClickHouse 的 uk.price-paid 表上运行了聚合查询:
- 从 uk.uk_price_paid_simple_partitioned 获取 2025 年总体汇总(计数、均值、中位数、最小值、最大值)
- 2025 年按月细分(交易数、均值、中位数)
- 2025 年按平均价格排名的顶级城镇(交易数 >= 50 的城镇)
- 年度对比:2024 年 vs 2025 年(计数、均值、中位数)
- 使用 uk.uk_price_paid 按房产类型细分 2025 年数据(计数、平均值、中位数)

关键数据(来自数据集)
- 2025 年总体(已记录交易):交易数 = 376,633;平均价格 = £362,282.66;中位数价格 = £281,000;最小值 = £100;最大值 = £127,700,000。
- 按月份(2025 年):(月份、交易数、平均价格、中位数价格)
  - 1 月:53,927,均值 £386,053,中位数 £285,000
  - 2 月:58,740,均值 £371,803,中位数 £285,000
  - 3 月:95,274,均值 £377,200,中位数 £315,000
  - 4 月:24,987,均值 £331,692,中位数 £235,000
  - 5 月:39,013,均值 £342,380,中位数 £255,000
  - 6 月:41,446,均值 £334,667,中位数 £268,500
  - 7 月:44,431,均值 £348,293,中位数 £277,500
  - 8 月:18,815,均值 £364,653,中位数 £292,999
  (数据集中仅包含 1-8 月的数据。)
- 按平均价格排名的顶级城镇(2025 年,交易数 ≥50 的城镇)
  - TRING:126 笔交易,平均 £1,973,274
  - BUCKHURST HILL:98 笔交易,平均 £1,441,331
  - ASCOT:175 笔交易,平均 £1,300,748
  - RADLETT:69 笔交易,平均 £1,160,217
  - COBHAM:115 笔交易,平均 £1,035,192
  - EAST MOLESEY、BEACONSFIELD、ESHER、CHALFONT ST GILES、THAMES DITTON 也位列前 10 名(均为高平均价格的通勤/富裕城镇)。
- 年度对比(2024 年 vs 2025 年已记录数据)
  - 2024 年:859,960 笔交易,均值 £390,879,中位数 £280,000
  - 2025 年:376,633 笔交易,均值 £362,283,中位数 £281,000
  (2025 年的计数要低得多,因为数据集仅包含部分年份数据。)
- 按房产类型(2025 年)
  - 独立式:85,362 笔交易,平均 £495,714,中位数 £415,000
  - 半独立式:107,580 笔交易,平均 £319,922,中位数 £270,000
  - 公寓:62,975 笔交易,平均 £298,529,中位数 £227,000
  - 联排式:112,832 笔交易,平均 £286,616,中位数 £227,000
  - 其他:7,884 笔交易,平均 £1,087,765(中位数 £315,000)— 注意小样本和异常值效应

重要注意事项和数据质量说明
- 2025 年的数据集不完整(仅包含 1 月至 8 月)。任何"2025 年"的总计都不是全年数据。
- 存在较大的异常值(例如,最大值 £127.7M,最小值 £100)。这些可能包括数据录入错误或非标准记录,会使均值偏高。在这种情况下,中位数通常是更稳健的度量指标。
- "其他"房产类型的平均值不稳定,原因是计数较低/异质性较大以及存在异常值。
- 我没有按 is_new、duration 或其他元数据进行过滤;这些过滤器可能会改变结果(例如排除新建房产或租赁房产)。
- 这些表是已支付价格类型的交易记录(已记录的销售)— 它们不直接代表要价或估值。

建议的后续步骤(我可以执行这些操作)
- 清除明显的异常值(例如,价格 < £10k 或 > £10M)并重新计算平均值/中位数。
- 生成区域/郡/邮编区域汇总和地图。
- 计算环比或滚动 3 个月中位数,以显示 2025 年的趋势。
- 按月生成同比(YoY)增长率(例如,2025 年 3 月 vs 2024 年 3 月)。
- 使用简单外推或时间序列建模预测 2025 年全年数据(但最好在决定如何处理缺失月份/异常值之后进行)。

如果您需要,我可以:
- 在移除极端异常值后重新运行相同的聚合查询并显示清理后的结果。
- 生成同比月度增长和图表(我可以返回 CSV 或 JSON 聚合数据供您制图)。
您希望我接下来执行哪项操作?
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_aggregator.database-anayst - 最后一个聚合器正在关闭,正在关闭所有持久连接...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - 正在断开所有持久服务器连接...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - clickhouse: 正在请求关闭...
[INFO] 2025-10-10T11:27:51 mcp_agent.mcp.mcp_connection_manager - 所有持久服务器连接已收到断开信号。
[INFO] 2025-10-10T11:27:52 mcp_agent.mcp.mcp_aggregator.database-anayst - 连接管理器已成功关闭并从上下文中移除
[INFO] 2025-10-10T11:27:52 mcp_agent.mcp_basic_agent - MCPApp 清理
{
  "data": {
    "progress_action": "已完成",
    "target": "mcp_basic_agent",
    "agent_name": "mcp_application_loop"
  }
}

前提条件​

安装依赖库​

设置凭据​

初始化 MCP Server 和 mcp-agent 代理​

前提条件

安装依赖库

设置凭据

初始化 MCP Server 和 mcp-agent 代理