mcp-toolbox 中 ClickHouse 集成：clickhouse-execute-sql 工具配置、实现与源码级解析-北京尧图网络

mcp-toolbox 中 ClickHouse 集成clickhouse-execute-sql 工具配置、实现与源码级解析【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxMCP Toolbox for Databases 将 ClickHouse 数据库暴露为 MCPModel Context Protocol服务供 LLM Agent 调用。其中clickhouse-execute-sql是最直接的一类工具它只接收一个sql参数将完整的 SQL 语句发送给指定 source 执行并返回结果。本文基于官方文档与仓库源码完整讲解该工具的 YAML 配置、参数约束、ClickHouse source 的连接配置、预置配置prebuilt用法以及从Invoke到RunSQL的底层调用链与错误处理方式。工具定位一条 SQL 直达 ClickHouseclickhouse-execute-sql工具的职责非常单一接收一个 SQL 语句针对配置的 source 执行它。它只声明一个输入参数sqlstring必填参数类型必填说明sqlstring是要在数据库上执行的 SQL 语句官方文档同时给出了明确的使用边界原文为英文 Note该工具面向“有人类在环”human-in-the-loop的开发者助手工作流不建议用于生产环境 Agent。原因在于它执行的是 LLM 自由生成的整条 SQL而不是预先约束好的参数化语句——对于需要在生产 Agent 中长期暴露的安全工具仓库中提供了另一类clickhouse-sql工具预编译语句声明式参数二者定位不同下文会展开对比。工具文档中还提到该工具具备查询日志query logging能力便于监控与调试从源码看ClickHouse source 在建立连接池时会通过 OpenTelemetry 创建连接 spansources.InitConnectionSpan见 clickhouse.go可与其他遥测/日志体系联动。工具配置YAML 写法与字段参考官方文档给出的标准配置示例如下kind: tool name: execute_sql_tool type: clickhouse-execute-sql source: my-clickhouse-instance description: Use this tool to execute SQL statements against ClickHouse.对应的字段参考Reference字段类型必填说明typestring是必须为clickhouse-execute-sqlsourcestring是要执行 SQL 的 ClickHouse source 名称descriptionstring是传递给 LLM 的工具描述这些约束并非只写在文档里而是有源码强制校验。在 clickhouseexecutesql.go 中工具类型常量在 L29 定义为const executeSQLType string clickhouse-execute-sql并通过init()注册到全局工具注册表Config结构体L49-L54对Type和Source标注了validate:required对应上面表格中的两个必填字段Initialize()L62-L65会显式检查Description为空时直接返回description is required for tool ...错误——也就是说description的必填同样在代码层强制。工具在初始化时还会做两件事声明参数通过parameters.NewStringParameter(sql, The SQL statement to execute.)声明唯一的sql参数L67-L68这是 LLM 端看到的 schema 来源设置 MCP 注解未显式配置annotations时默认套用tools.NewDestructiveAnnotationsL73。从命名和 MCP 注解语义看这表明工具默认被标记为“可能产生破坏性操作”的提示性注解客户端如 Claude Desktop可据此展示确认提示。此外Config还支持可选的annotations字段L53允许在配置中覆盖默认注解行为。仓库中的单元测试 clickhouseexecutesql_test.go 验证了上述 YAML 能被正确解析为Config{Name, Description, Type, Source}即“文档示例”与“解析器实现”是一致的。运行时调用链从 Invoke 到 RunSQL工具被 Agent 调用时执行路径如下代码位于 clickhouseexecutesql.go源兼容性检查ValidateSourceL94-L100在配置校验阶段就要求 source 实现compatibleSource接口L45-L47——即必须提供RunSQL(context.Context, string, parameters.ParamValues) (any, error)方法。ClickHouse source 正好实现了该方法。若 source 类型不符会得到invalid source for ... tool: source ... is not a compatible type错误参数取值InvokeL102-L117从params.AsMap()中取出sql并断言为字符串类型不匹配会返回 Agent 错误unable to cast sql parameter ...委托 source 执行最终调用source.RunSQL(ctx, sql, nil)——注意第三个参数传的是nil即该工具不支持绑定参数SQL 必须自包含错误分类执行错误经util.ProcessGeneralError(err)转换为 Toolbox 的统一错误类型返回给调用方。source 端RunSQL 如何组织结果ClickHouse source 的RunSQL实现在 clickhouse.gointernal/sources/clickhouse/clickhouse.go通过s.ClickHousePool().QueryContext(ctx, statement, sliceParams...)执行语句execute-sql传入的参数为nil因此sliceParams为空使用results.Columns()与results.ColumnTypes()读取列名和列类型逐行Scan后将结果组织为[]any其中每一行是一个map[string]any列名 - 值对 ClickHouse 驱动返回的String/FixedString列做了专门处理若值是[]byte则转为string否则原样保留L145-L159因此该工具的返回值形如“每行一个列名映射”的数组可被 MCP 客户端序列化为 JSON 列表交给 LLM 阅读。配套 ClickHouse Source 配置clickhouse-execute-sql依赖一个type: clickhouse的 source。官方 source 文档给出了完整的字段参考与两类连接示例。Source 字段参考字段类型必填说明typestring是必须为clickhousehoststring是主机名或 IP如clickhouse.example.comportstring是端口HTTPS 常见8443HTTP 常见8123databasestring是要连接的数据库名userstring是用户名passwordstring否密码protocolstring否https默认或httpsecureboolean否是否使用 TLS 安全连接默认false连接示例安全连接HTTPS端口 8443kind: source name: secure-clickhouse-source type: clickhouse host: clickhouse.example.com port: 8443 database: analytics user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: https secure: trueHTTP 协议连接端口 8123kind: source name: http-clickhouse-source type: clickhouse host: localhost port: 8123 database: logs user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} protocol: http secure: false文档建议使用${ENV_NAME}形式的环境变量替换来注入凭据避免把密钥硬编码进配置文件。源码侧的连接细节从 clickhouse.go 的连接池初始化逻辑L180-L215可以看到几个对实际运行有影响的事实protocol 缺省为 httpsprotocol 时被赋值为httpsL185-L187合法取值由validateConfig限定为http/httpssecure 对 scheme 的影响当protocol http且secure: true时实际 DSN 的 scheme 会被改写为httpsL198-L200DSN 构造与 TLS 参数用户名/密码经url.QueryEscape编码后拼入 DSNHTTPS 场景追加?securetrueskip_verifyfalseL201-L204即不跳过证书校验连接池参数SetMaxOpenConns(25)、SetMaxIdleConns(5)、SetConnMaxLifetime(5 * time.Minute)L211-L213这些是硬编码在源码中的默认值启动即探活Initialize在创建池后会执行PingContext连接失败会关闭池并返回unable to connect successfullyL66-L76保证坏配置在启动期暴露而非运行期。预置配置--prebuilt clickhouse如果不想手写 source tool 的 YAML可以使用内置预置配置。仓库中的实际定义文件是 clickhouse.yaml它声明了一个 source 与三个工具并打包为工具集kind: source name: clickhouse-source type: clickhouse host: ${CLICKHOUSE_HOST} port: ${CLICKHOUSE_PORT} user: ${CLICKHOUSE_USER} password: ${CLICKHOUSE_PASSWORD} database: ${CLICKHOUSE_DATABASE} protocol: ${CLICKHOUSE_PROTOCOL} --- kind: tool name: execute_sql type: clickhouse-execute-sql source: clickhouse-source description: Use this tool to execute SQL. --- kind: tool name: list_databases type: clickhouse-list-databases source: clickhouse-source description: Use this tool to list all databases in ClickHouse. --- kind: tool name: list_tables type: clickhouse-list-tables source: clickhouse-source description: Use this tool to list all tables in a specific ClickHouse database. --- kind: toolset name: clickhouse_database_tools tools: - execute_sql - list_databases - list_tables按预置配置文档的说明使用--prebuilt clickhouse启动时需要设置以下环境变量环境变量含义CLICKHOUSE_HOSTClickHouse 服务器主机名或 IPCLICKHOUSE_PORT端口CLICKHOUSE_USER数据库用户名CLICKHOUSE_PASSWORD数据库密码CLICKHOUSE_DATABASE要连接的数据库名CLICKHOUSE_PROTOCOL连接协议如 http预置配置提供三个工具execute_sql本文主题、list_databases、list_tables并默认聚合为clickhouse_database_tools工具集。与 clickhouse-sql 的分工何时用 execute-sql同一个 ClickHouse source 下仓库还提供了 clickhouse-sql 工具。两者的关键差异维度clickhouse-execute-sqlclickhouse-sql输入完整 SQL 语句sql参数固定的statement模板声明式parameters预编译语句绑定值参数绑定无RunSQL传nil支持?占位符绑定还可用templateParameters做模板替换适用场景开发者助手、人在环的一次性查询/运维语句面向 Agent 的长期暴露、需要参数化约束的查询也就是说临时排查、一次性聚合分析、DDL 探查等“人确认后再执行”的场景适合execute-sql而要把工具挂给生产 Agent 长期运行、且希望把 SQL 结构锁死只允许 LLM 填参数时应选clickhouse-sql。这也呼应了本文开头提到的官方使用边界说明。小结与验证路径配置入口kind: tooltype: clickhouse-execute-sql 必填的source、description源码在 clickhouseexecutesql.go 中强制校验运行时Invoke-compatibleSource.RunSQL(ctx, sql, nil)-*sql.DB.QueryContext- 结果转为行级列名映射数组clickhouse.go L108-L169快速起步--prebuilt clickhouse 六个CLICKHOUSE_*环境变量clickhouse.yaml可参考的测试与文档YAML 解析测试、source 参考文档、预置配置文档。最后再次强调适用前提clickhouse-execute-sql执行的是 LLM 生成的任意 SQLsource 的IsReadOnly()返回falseclickhouse.go L92-L94因此请确保所用数据库账号权限与暴露范围相匹配并优先用于有人类审核的工作流。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

mcp-toolbox 中 ClickHouse 集成：clickhouse-execute-sql 工具配置、实现与源码级解析

相关推荐

Java实现真正可玩的连连看游戏：路径判定与可解关卡生成

C# OpenCV仿射变换实现与优化指南

2026年Java商城系统选型：安全性、扩展性与落地成本三角平衡

更多资讯

光模块固晶机伺服选型：精度、力控与TSN同步实战指南

C#调用PaddleOCR实战：DeploySharp框架高效部署指南

深入解析SQLAlchemy：从ORM核心机制到生产环境实战指南

Qt实现YY语音房间功能：跨平台语音社交应用开发指南

RustFox：10MB轻量API调试工具技术解析

OpenSandbox SDK Telemetry 详解：沙箱创建耗时指标的上报链路、服务端落地与禁用方式

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？