MCP Toolbox 的 tools.yaml 分步配置指南：从第一个数据源到可用的工具集

MCP Toolbox 的 tools.yaml 分步配置指南：从第一个数据源到可用的工具集

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

刚装好 MCP Toolbox for Databases（一个面向数据库的 MCP 服务器），第一件事就是写它的配置文件 tools.yaml。最常见的翻车现场是：文件存了，toolbox serve也跑了，但客户端里一个工具都看不到。原因几乎都是下面三种之一：source 的连接参数没给全、tool 的 source 字段没对上名字、环境变量的写法漏了符号。这篇指南按"接数据源 → 挂工具 → 打包工具集"三步走，走完你就能独立配出一份能用的 tools.yaml。

先看全局：source、tool、toolset 各管什么

tools.yaml 用多文档 YAML 书写，三类块用---分隔，靠kind字段区分：

• kind: source：定义一个数据库连接，给连接取个唯一名字；
• kind: tool：定义一个可被调用的动作，用source字段指向某个数据源的名字；
• kind: toolset：把若干工具打包成一个组，方便一次性加载。

启动时工具加载的入口：toolbox serve --config tools.yaml。--config指定要加载哪个文件（默认就是 tools.yaml），加载顺序固定为 source → tool → toolset，后面的块引用前面的名字。

第一步：接入一个 MySQL 数据源

先写最小的 source 块，只留必需项。type 填数据库类型（这里是 mysql），其余字段就是标准连接参数：

kind: source name: mysql-source type: mysql host: localhost port: 3306 database: mydb user: toolbox_user password: secret

可选参数按需追加，不必一次写全：

参数	作用	是否必需
type	数据库类型，如 mysql、postgres、sqlite	必需
name	数据源在配置内的唯一名字，工具靠它被引用	必需
host / port / database / user / password	标准连接参数	通常必需（个别类型例外）
queryTimeout	查询超时，如30s	可选
queryParams	追加的连接串参数，如时区设置	可选

仓库里 mysql 的完整预置长这样：host: ${MYSQL_HOST:localhost}、queryTimeout: 30s，可以直接对照。

第二步：给数据源挂上工具

执行 SQL 的基础工具

工具块只需四个字段：type 决定工具行为，source 把 source 指向数据源名字，description 写给 Agent 看、说清楚这个工具干什么：

kind: tool name: execute_sql type: mysql-execute-sql source: mysql-source description: Use this tool to execute SQL.

带模板参数的 SQL 工具

固定语句的工具用statement写 SQL，用templateParameters声明 SQL 里的{{.名字}}占位符，占位符会在执行前被替换进语句：

kind: tool name: inspect_table type: mysql-sql source: mysql-source description: 返回指定表的建表语句 statement: SHOW CREATE TABLE {{.tableName}}; templateParameters: - name: tableName type: string description: 要查看的表名

注意 templateParameters 里的name必须和 statement 中{{.xxx}}的 xxx 逐字一致。

带默认值的环境变量写法

敏感信息不要写死在文件里。${变量名}引用环境变量，${变量名:默认值}在变量未设置时兜底：

user: ${MYSQL_USER} password: ${MYSQL_PASSWORD} port: ${MYSQL_PORT:3306}

第三步：把工具打包成工具集并验证加载

toolset 块只声明 name 和 tools 列表，列表里填的是工具的名字：

kind: toolset name: mysql_basic tools: - execute_sql - inspect_table

作用是把相关工具归成一组：给不同 Agent 或不同应用暴露不同组合时，按 toolset 名加载即可，不必每次手挑工具。配完启动toolbox serve --config tools.yaml，看日志里工具是否全部注册；再打开 Web UI 的 Tools / Toolsets 页面确认列表齐全，就能接 MCP 客户端了。

一份可以直接跑的最小完整示例

四个块放同一个文件，---分隔。设好MYSQL_PASSWORD后启动，即可得到两个可用工具和一个工具集：

kind: source name: mysql-source type: mysql host: localhost port: 3306 database: mydb user: toolbox_user password: ${MYSQL_PASSWORD} --- kind: tool name: execute_sql type: mysql-execute-sql source: mysql-source description: Use this tool to execute SQL. --- kind: toolset name: mysql_basic tools: - execute_sql

自查清单：五个最容易配错的点

• 启动报"找不到 source" → 检查每个 tool 的source值是否与 source 块的name逐字一致，包括大小写。
• 工具一个都没加载 → 检查每块的kind拼写（source / tool / toolset），以及块之间是否都有---分隔行。
• 连接被数据库拒绝 → 先手动用同样参数连一次库，排除密码、端口和 host 本身的问题，再看配置。
• 环境变量没生效、连接串里出现字面量${...}→ 确认写法是${NAME:默认值}，冒号在右括号内，${ NAME }里带空格或引号都不行。
• toolset 加载时缺工具或报错 → 对照 tools 列表和已定义的 tool 名字，列表里不能出现没定义过的名字。

配完这三板块，tools.yaml 就算立起来了。想加数据库类型时，参考 internal/prebuiltconfigs/tools/ 下的预置配置（比如 mysql.yaml、postgres.yaml）照抄结构；字段细则见 docs/en/documentation/configuration/。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox