MCP Toolbox for Databases 预置配置实战：一条命令接入 Cloud SQL for MySQL

MCP Toolbox for Databases 预置配置实战一条命令接入 Cloud SQL for MySQL【免费下载链接】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 中的cloud-sql-mysql预置配置prebuilt config展开说明如何通过--prebuilt参数零配置文件启动服务、需要设置哪些环境变量与 IAM 权限并结合仓库源码剖析连接池建立Cloud SQL Go Connector、mTLS、IAM 认证、只读模式实现以及预置工具集SQL 执行、诊断监控、实例生命周期管理的完整组成帮助你把 Cloud SQL for MySQL 快速接入任意 MCP 客户端并获得可直接运行的数据库操作能力。什么是 cloud-sql-mysql 预置配置MCP Toolbox 的核心概念是把数据库连接封装为source并把可执行操作封装为tool。通常你需要手写一份包含多个 source 和 tool 定义的 YAML 配置文件而预置配置则把这一整套定义预先打包在二进制内只需一个--prebuilt参数即可加载。cloud-sql-mysql是预置配置之一对应参数值为cloud-sql-mysqltoolbox serve --prebuilt cloud-sql-mysql从源码结构看该配置在编译期通过//go:embed tools/*.yaml内嵌进二进制见 prebuiltconfigs.go。启动时的加载逻辑是遍历内嵌tools目录下的所有.yaml文件用去掉.yaml后缀的文件名作为 source type 键名如cloud-sql-mysql.yaml对应键cloud-sql-mysql见 loadPrebuiltToolYAMLs--prebuilt参数本身在 flags.go 中定义帮助文本会自动列出全部可用值。命令行传入的值若找不到对应配置Get会返回包含可用列表的错误信息prebuiltconfigs.go#L48-L59。预置配置的实际内容定义在 cloud-sql-mysql.yaml 中包含 3 个 source、19 个 tool 和 4 个 tool group下文逐层展开。环境变量配置预置配置通过环境变量注入连接信息全部变量统一使用CLOUD_SQL_MYSQL_前缀。结合 YAML 中的${VAR:default}占位符语法各变量的必填性与默认值如下环境变量对应配置字段是否必填默认值说明CLOUD_SQL_MYSQL_PROJECTproject是无GCP 项目 IDCLOUD_SQL_MYSQL_REGIONregion是无Cloud SQL 实例所在区域如us-central1CLOUD_SQL_MYSQL_INSTANCEinstance是无Cloud SQL 实例 IDCLOUD_SQL_MYSQL_DATABASEdatabase是无要连接的数据库名CLOUD_SQL_MYSQL_USERuser否空数据库用户名留空则走 IAM 认证CLOUD_SQL_MYSQL_PASSWORDpassword否空数据库用户密码留空则尝试 IAM 认证CLOUD_SQL_MYSQL_IP_TYPEipType否PUBLICIP 类型取值为public或privateCLOUD_SQL_MYSQL_READONLYreadOnly否false设为true时强制连接只读并抑制写操作工具在 YAML 中带默认值的变量写作${CLOUD_SQL_MYSQL_IP_TYPE:PUBLIC}与${CLOUD_SQL_MYSQL_READONLY:false}即未设置时分别回落到PUBLIC和falsecloud-sql-mysql.yaml#L22-L25。而PROJECT、REGION、INSTANCE、DATABASE四个变量没有默认值占位从源码结构看source 的Config结构体中project、region、instance标注了validate:requiredcloud_sql_mysql.go#L53-L65缺失时配置校验会失败。一个典型的服务启动方式export CLOUD_SQL_MYSQL_PROJECTmy-project-id export CLOUD_SQL_MYSQL_REGIONus-central1 export CLOUD_SQL_MYSQL_INSTANCEmy-instance export CLOUD_SQL_MYSQL_DATABASEmy_db export CLOUD_SQL_MYSQL_USERmy-mysql-user export CLOUD_SQL_MYSQL_PASSWORDmy-password # 可选export CLOUD_SQL_MYSQL_IP_TYPEprivate # 可选export CLOUD_SQL_MYSQL_READONLYtrue toolbox serve --prebuilt cloud-sql-mysql该预置配置在内部展开为 3 个 source见 cloud-sql-mysql.yaml#L15-L36cloud-sql-mysql-sourcetype: cloud-sql-mysql上述环境变量全部作用于此 source负责建立到 Cloud SQL 实例的数据连接池cloud-sql-admin-sourcetype: cloud-sql-admin基于 Cloud SQL Admin API复用CLOUD_SQL_MYSQL_PROJECT与CLOUD_SQL_MYSQL_READONLY提供实例管理工具cloud-monitoring-sourcetype: cloud-monitoring连接 Cloud Monitoring提供基于 PromQL 的指标查询工具。IAM 权限要求要让 MCP Toolbox 成功连接并操作实例运行身份需要两类权限Cloud SQL Clientroles/cloudsql.client通过 Cloud SQL Go Connector 建立 mTLS 连接所必需。从源码结构看连接走cloud.google.com/go/cloudsqlconn的 dialercloud_sql_mysql.go该 connector 使用你的 Application Default CredentialsADC完成授权因此需要先为运行环境配置好 ADC数据库层权限如SELECT、INSERT实际执行 SQL 时由 MySQL 侧校验需授予给所连接的数据库用户。如果服务运行在 Compute Engine 上VM 的服务账号还需要具备调用 Cloud SQL Admin API 的 scope否则cloud-sql-admin-source相关的管理工具无法工作。认证方式上source 支持两种模式见 source.md 的 Authentication 一节用户/密码认证user与password都提供时直接使用凭据登录IAM 认证user留空时Toolbox 自动从 ADC 中解析出邮箱作为 MySQL IAM 用户或显式把user设为 IAM 邮箱password留空。这两种模式的分支逻辑在 getConnectionConfig 中实现两者都提供则关闭 IAMuser为空则调用GetIAMPrincipalEmailFromADC(ctx, mysql)获取邮箱只提供密码不提供用户会直接报错。另外user与password在 DSN 拼装中也是区分开路的见 buildDSN。只读模式连接级强制 工具级抑制CLOUD_SQL_MYSQL_READONLYtrue是这个预置配置的一个值得注意的设计。从源码看它有双重效果连接级只读readOnly为true时DSN 中会追加connectionAttributesread_only_connection:true由 Cloud SQL 连接器在会话层强制只读buildDSN工具级抑制source 暴露IsReadOnly()接口cloud_sql_mysql.go#L97-L99框架据此在 MCP 工具列表层面隐藏写操作类工具即suppresses write-capable tools——即使模型尝试调用写工具也不会在可用工具中暴露。值得注意的是预置 YAML 中readOnly同时作用于cloud-sql-mysql-source和cloud-sql-admin-source两处cloud-sql-mysql.yaml#L25-L31因此开启只读后Admin 侧的create_instance、create_backup等变更类操作同样会被抑制适合把 Toolbox 以只读分析助手的角色接入生产环境。预置工具集详解cloud-sql-mysql预置配置共注册 19 个工具按来源 source 可分为三组。文档中列出的核心 9 个 MySQL 诊断工具如下工具名即 MCP 客户端中可直接调用的名字数据访问与 SQL 诊断工具实现类型功能execute_sqlmysql-execute-sql执行 SQL 查询并返回结果集list_tablesmysql-list-tables以 JSON 列出用户自建表的结构信息对象类型、列、约束、索引、触发器、注释可按逗号分隔的表名过滤get_query_planmysql-get-query-plan对单条 SQL 语句返回执行计划不实际执行用于性能分析与索引评估list_active_queriesmysql-list-active-queries从processlist与innodb_trx中列出 top N默认 10进行中的查询按执行时长降序包含进程 ID、事务时长、锁定行数等list_tables_missing_unique_indexesmysql-list-tables-missing-unique-indexes找出缺少主键或唯一键约束的表用于数据完整性治理list_table_fragmentationmysql-list-table-fragmentation按数据/索引文件大小与空闲空间计算每表的碎片率碎片率高的表可用OPTIMIZE TABLE回收空间list_all_locksmysql-list-all-locks列出指定库中按查询执行时长降序的 top N默认 10锁show_query_statsmysql-show-query-stats展示查询执行统计执行次数、总/平均/最大延迟、扫描行数、全表扫描与低效索引使用list_table_statsmysql-list-table-stats展示表级统计表大小、总延迟、读写行数、读写延迟可按库或表过滤默认返回 10 条这 9 个工具全部挂在cloud-sql-mysql-source上工具描述文本直接从 YAML 继承cloud-sql-mysql.yaml#L37-L89每个工具均有独立实现包如 mysqlexecutesql、mysqlgetqueryplan、mysqllistactivequeries并配套对应的_test.go单元测试。执行链路方面所有 SQL 最终经由 source 的RunSQL方法执行cloud_sql_mysql.go#L133-L186先用sqlcommenter在语句前追加注释标签再走连接池QueryContext逐行把结果转换为保序的行映射orderedmap.Row返回保证 MCP 响应中列顺序稳定。实例生命周期管理Admin 类挂在cloud-sql-admin-source上用于管理 Cloud SQL 实例本身工具实现类型功能create_instancecloud-sql-mysql-create-instance创建 MySQL 实例MySQL 专用实现见 cloudsqlmysqlcreateinstanceget_instancecloud-sql-get-instance查询实例详情list_instancescloud-sql-list-instances列出项目下的实例create_databasecloud-sql-create-database创建数据库list_databasescloud-sql-list-databases列出数据库create_usercloud-sql-create-users创建数据库用户create_backupcloud-sql-create-backup创建备份restore_backupcloud-sql-restore-backup从备份恢复clone_instancecloud-sql-clone-instance克隆实例wait_for_operationcloud-sql-wait-for-operation等待 Admin 长操作完成YAML 中配置了multiplier: 4延长等待预算监控指标PromQL 类挂在cloud-monitoring-source上通过 Cloud Monitoring 的 Prometheus 兼容接口查询时序指标get_system_metrics查询 MySQL 实例的系统级指标YAML 中内嵌了完整的指标字典与 PromQL 构造规则——包括 CPU 利用率、连接数、网络收发字节、内存组件、磁盘 IO、InnoDB buffer pool 页面、open_tables等 24 个cloudsql.googleapis.com/*指标以及avg_over_time、topk、quantile等 8 种查询示例默认窗口5mget_query_metrics查询语句级指标Database Insights涵盖dbinsights.googleapis.com/aggregate/*、perquery/*、pertag/*三类共 18 个指标执行时间、执行次数、锁等待、IO 等待、行数等支持按query_hash下钻到单条语句。这两段指标说明直接写在 cloud-sql-mysql.yaml#L122-L216相当于内置的指标知识库让模型在生成 PromQL 时有据可依。工具分组Tool Groups预置 YAML 除了注册工具还定义了 4 个 tool groupcloud-sql-mysql.yaml#L234-L278为 MCP 客户端提供按场景订阅工具子集的能力admincreate_instance、get_instance、list_instances、create_database、list_databases、create_user、wait_for_operation——用于实例/库/用户供给与操作进度跟踪dataexecute_sql、list_tables、get_query_plan、list_active_queries——用于探查 schema 与交互式查询monitorget_query_plan、list_active_queries、list_all_locks、get_query_metrics、get_system_metrics、list_table_fragmentation、list_table_stats、list_tables_missing_unique_indexes、show_query_stats——用于慢查询排障、PromQL 指标分析与结构性性能问题碎片、缺唯一索引识别lifecyclecreate_backup、restore_backup、clone_instance、list_instances、get_instance、wait_for_operation——用于备份、恢复与实例克隆。group 的解析与注册由 group.go 完成其测试 group_test.go 验证了 group 与工具的归属关系。配置校验与启动行为了解以下源码行为有助于排查接入问题启动即连接验证Initialize在建池后立即执行PingContext连接失败会关闭池并返回错误即toolbox serve启动阶段就能暴露凭据/网络问题而不会等到第一次工具调用才失败cloud_sql_mysql.go#L71-L88驱动按 source 名隔离每个 source 注册独立的驱动名cloudsql-mysql-source_name避免多个 source 配置之间互相干扰cloud_sql_mysql.go#L264-L271默认 IP 类型newConfig中IPType初始化为public与文档中Default: Public一致cloud_sql_mysql.go#L45-L51无论public还是private连接都经过 IAM 授权 mTLS 加密版本探测source 通过SELECT VERSION()获取 MySQL 版本、通过SHOW VARIABLES LIKE performance_schema探测performance_schema是否开启cloud_sql_mysql.go#L117-L131后者影响依赖 performance_schema 的诊断工具如锁、表统计类的行为。端到端的接入验证可以在 tests/cloudsqlmysql/cloud_sql_mysql_integration_test.go 中参考其测试流程若你打算通过 MCP 协议联调tests/cloudsqlmysql/cloud_sql_mysql_mcp_test.go展示了 MCP 层调用方式。小结cloud-sql-mysql预置配置把数据访问 诊断监控 实例管理三类能力打包为一个--prebuilt值用 4 个必填环境变量定位实例、可选变量选择认证与网络模式CLOUD_SQL_MYSQL_READONLY提供连接级只读强制。它的全部定义可追溯到 cloud-sql-mysql.yaml连接实现位于 cloud_sql_mysql.go各诊断工具实现位于 internal/tools/mysql 下按工具名划分的包中。若你的实例已启用 IAM 登录建议直接留空user/password走 ADC 认证若面向生产环境暴露只读分析能力则务必设置CLOUD_SQL_MYSQL_READONLYtrue让框架在连接层与工具列表两层同时兜住写操作。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考