MCP Toolbox 配置速成：10 分钟跑通 tools.yaml，让 AI 连上第一个 MySQL-育师

MCP Toolbox 配置速成：10 分钟跑通 tools.yaml，让 AI 连上第一个 MySQL

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

给 AI 助手接上"查数据库的手"，是 MCP Toolbox 最典型的用法。它本身是一个数据库专用的 MCP 服务器，你把连接信息写进一个 YAML 文件，AI 端就能调用工具查表、跑 SQL。跟完本文，你手里会有一份能直接启动的 tools.yaml，以及一个在 8080 端口监听的本地服务。

一张图看懂 tools.yaml 的模块关系

整个文件由若干段以---分隔的 YAML 文档组成，每段用kind字段区分角色。source 只管"怎么连库"，tool 只管"能做什么"，toolset 只管"把哪些 tool 打包给哪个 Agent"。三者靠名字互相引用，谁也不依赖谁的内容。

最小可运行配置：先跑通再说

把下面这段存为tools.yaml，它已经足够启动：

kind: source name: mysql-source # source 块的唯一名字 type: mysql # 数据源类型 host: ${MYSQL_HOST:localhost} port: ${MYSQL_PORT:3306} database: ${MYSQL_DATABASE} user: ${MYSQL_USER} password: ${MYSQL_PASSWORD} --- kind: tool name: execute_sql type: mysql-execute-sql # 工具类型：执行 SQL source: mysql-source # 必须指向上面 source 的 name description: Use this tool to execute SQL.

必填与可选字段一次看全：

字段	必填	作用
name	是	块内唯一名字，被其他块引用
type	是	决定行为，如 mysql、postgres
host / port / database	是	连接地址三件套
user / password	是	数据库账号，建议走环境变量
queryParams	否	附加连接参数
queryTimeout	否	查询超时，如`30s`

启动服务：

toolbox serve --config tools.yaml --address 0.0.0.0 --port 8080

看到监听日志后，AI 端连上 8080 即可发现execute_sql这个工具。

source 块：可选字段怎么加

source 是唯一直接接触数据库的块。最小配置里没写queryParams和queryTimeout，补上后是这样（只展示增量行）：

queryParams: ${MYSQL_QUERY_PARAMS:} # 冒号后留空表示可为空 queryTimeout: 30s # 单条查询的超时上限

type不同，字段也不同：sqlite 只需要database路径，BigQuery 只需要项目与位置，不需要 host 和 port。各类型的完整字段见 source 文档和预置配置目录。

tool 块：参数化工具怎么写

动态 SQL 工具（如mysql-execute-sql）让 Agent 自由写 SQL，灵活但不设防。固定流程更推荐参数化工具：SQL 结构写死，输入只能填进占位符，天然防注入。

kind: tool name: search-hotels-by-name type: postgres-sql # 自定义 SQL 工具 source: my-pg-source description: Search for hotels based on name. statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%'; parameters: # $1 对应第一个参数 - name: name type: string description: The name of the hotel.

statement里的$1是 Postgres 占位符，MySQL 用?。参数顺序必须与parameters列表一致。

toolset 块：把工具按用途打包

一个 AI 应用往往只该看到一部分工具。toolset 就是工具清单：

kind: toolset name: monitor tools: - list_active_queries - list_all_locks - show_query_stats

需要同时打包 prompts（预置提示词）时，改用kind: group，多一个prompts字段即可；kind: toolset只是只含工具的分组，老配置无需改动。

敏感信息：环境变量统一处理

规则只有一条：密钥类字段不落盘。引用格式是${ENV_NAME}，可带默认值${ENV_NAME:default}：

password: ${MYSQL_PASSWORD} # 未设置时启动直接报错，安全 port: ${DB_PORT:3306} # 未设置时回落到 3306

password、API key 一律不设默认值；host、port 这类非机密字段可以设，方便本地快速启动。

排错速查：按出现频率排序

报错现象	可能原因	修复动作
tool 引用了不存在的 source	`source`字段拼写与 source 块`name`不一致	逐字对照改名
connection refused / timeout	host、port 错，或数据库没启动	`telnet`测端口，先确认库是活的
access denied	环境变量值错或指向了错误账号	`echo $MYSQL_PASSWORD`核对
启动报缺少字段	`${MYSQL_DATABASE}`这类变量为空	设置变量，或补`${VAR:default}`
unknown tool type	`type`拼错，或本地版本过旧	对照 CLI 参考修正；配置里开`ignoreUnknownTools`可跳过未知类型并只告警

进阶技巧：三条真正省时间的做法

复用预置配置，不用从零写。仓库内置几十套现成工具，直接--prebuilt=postgres加载整套；--prebuilt=postgres/data还能只取其中一个工具集，并可叠加--config混入自己的自定义工具。
改配置不用重启服务。Toolbox 会轮询 tools.yaml 的变化，保存即生效；轮询间隔由pollInterval控制，确定不再改动时用disableReload关掉。
按最小权限发账号。给 Agent 的数据库账号只授SELECT；固定查询走参数化工具，execute-sql类动态工具只留给可信的探索场景。

速查表与下一步

块	kind	干什么	关键必填字段
数据源	source	声明怎么连库	name, type, host, port, database, user, password
工具	tool	声明一个可调用动作	name, type, source
工具集	toolset	打包多个工具	name, tools
分组	group	打包 tools + prompts	name, tools 或 prompts