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.

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

启动服务：

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 这类非机密字段可以设，方便本地快速启动。

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

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

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

速查表与下一步

关键路径：配置总览在 configuration 文档，可直接抄的完整样例在 预置配置目录。下一步：把type改成 postgres，连上你自己的第一个库。

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