5分钟写好tools.yaml:数据库接入AI助手【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox想让 AI 助手直接回答orders 表今天有多少单这种问题MCP Toolbox 就是干这个的。它是 Google 开源的数据库 MCP 服务器把 MySQL、PostgreSQL、AlloyDB 等数据库的能力通过 MCP 协议暴露给 AI 助手而这一切都由一份 tools.yaml 定义。 tools.yaml 三层引用关系一图看懂先记住三种资源的关系tool 通过source字段指向数据源toolset 通过tools列表收纳 tool。可以类比成水管source 是总水管tool 是水龙头toolset 是同时打开一组龙头的钥匙。MCP Toolbox for Databases 支持接入的数据源范围比想象中大得多架构上 AI 客户端只连 toolbox 一个入口 最小可运行的 tools.yaml 长什么样下面这份配置假设环境变量已导出即可直接启动kind: source # 数据源MySQL 连接信息 name: mysql-source # 唯一标识被 tool 用 source 字段引用 type: mysql host: ${MYSQL_HOST:localhost} # 环境变量未设置时回退到 localhost port: ${MYSQL_PORT:3306} database: ${MYSQL_DATABASE} user: ${MYSQL_USER} password: ${MYSQL_PASSWORD} --- kind: tool # 开箱即用工具直接执行 SQL name: execute_sql type: mysql-execute-sql source: mysql-source # 必须和上面 source 的 name 完全一致 description: Use this tool to execute SQL. --- kind: toolset # 工具集把工具打包给客户端 name: data tools: - execute_sql用大白话过一遍第一段是连谁、怎么连name是别处引用的标识符host/port/database/user/password 就是连接信息第二段是暴露什么能力type决定工具种类mysql-execute-sql是内置行为不用写任何 SQLdescription是给 AI 读的说明第三段只是把工具名字列进一个组AI 客户端可以按组一次性拉走。官方内置的 MySQL 配置比这份丰富得多值得对照internal/prebuiltconfigs/tools/mysql.yaml三层各自解决什么问题sources 连接层连接串怎么写sources 层只回答一个问题toolbox 怎么连上数据库。连接字段由type决定——MySQL 用 hostportCloud SQL 类用的是 projectinstance。接多个库就在同一文件里多写几段kind: source各自给不同的namekind: source name: pg-source type: postgres host: ${POSTGRES_HOST:localhost} port: ${POSTGRES_PORT:5432} database: ${POSTGRES_DATABASE} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD}source 的name全局只能出现一次重名启动直接失败。环境变量怎么引用${MYSQL_PASSWORD}是标准写法启动时 toolbox 会把文件里所有${...}替换成进程环境变量的值冒号语法${VAR:默认值}表示变量没设置时用默认值上面 host 缺省就是 localhost。建议非机密字段带默认值方便本地跑password 这类敏感值不设默认值——忘配变量时启动立刻报错好过悄悄用错值连上去。完整说明见官方文档docs/en/documentation/configuration/_index.mdtools 能力层两种工具写法tools 层回答AI 能采取哪些动作常见两类开箱即用工具只声明type行为内置。mysql-execute-sql直接执行 SQLmysql-list-tables列表postgres-list-active-queries查正在跑的查询一行代码都不用写。模板工具自己写死 SQL声明输入参数把一个命名查询变成工具。官方示例kind: tool name: search-hotels-by-name type: postgres-sql source: pg-source description: Search for hotels based on name. parameters: - name: name type: string description: The name of the hotel. statement: SELECT * FROM hotels WHERE name ILIKE % || $1 || %;注意statement里用$1占位符引用参数避免把用户输入直接拼进 SQL这是防注入的底线写法。toolsets 分组层为什么打包、按什么粒度拆toolsets 层回答工具怎么交付给客户端客户端可以按组名一次拉取整组工具不用逐个枚举。拆组的价值在规模上来之后才明显——官方 mysql 配置就是按场景拆的data组收 execute_sql、list_tables 这类日常查询工具monitor组收锁、碎片率、查询统计这类诊断工具。值班场景只给 AI 挂 monitor 组它就不会碰到查询以外的东西。粒度原则按使用场景分组而不是按表分组一组 3~10 个工具为宜。启动时配置怎么被加载顺序是先全部解析、再替换变量、最后才建连接。任何一个 source 连接失败启动就停在这一步tool 和 toolset 阶段只做名字校验。所以整条链路只有一条铁律名字必须一字不差地对上。⚠️ 三个高频坑现象到修法一次说清坑一数据源连不上。现象启动日志报某个 source 初始化失败提示连接超时或 access denied。原因host/port 写错、账号密码不对、或网络到不了数据库。修法逐字段核对连接串拿同一账号手工连一次确认凭据本身没问题再检查防火墙与安全组。坑二工具找不到数据源。现象启动时报 tool 引用的 source 不存在。原因tool 的source字段和 source 的name对不上多为手敲时漏了后缀或大小写不一致。修法直接从 source 定义里复制 name 粘贴过去。坑三环境变量没生效。现象启动报环境变量解析错误或悄悄走了默认值。原因有两种写法漏了$或花括号变量只在另一个 shell 里 export 过启动 toolbox 的进程根本看不到。修法统一写成${VAR:默认值}在同一个会话里先 export、再启动 toolbox。三条值得记住的做法敏感信息一律走环境变量。密码、API key 不进 yaml否则文件迟早被贴进聊天记录或截图里。description 是写给 AI 看的说明书要具体。官方 mysql 配置里list_active_queries的描述写明了数据来源表、排序方式、返回哪些字段AI 第一次调用就能用对只写一句查询工具等于没写。工具集按运维场景拆。日常查询一组、诊断监控一组、管理类一组每个客户端只挂自己需要的组工具面越聚焦AI 选错工具的概率越低。收束tools.yaml 本质是三类资源source 管连接、tool 管能力、toolset 管交付粒度名字对上、机密不落文件这两点占掉了九成踩坑面积。剩下的是照着现成模板改参数——仓库内置了各数据库类型的完整配置直接打开目录抄一份当模板internal/prebuiltconfigs/tools/【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考