用 MCP Toolbox 连接 Cloud SQL for PostgreSQL数据库 MCP Server 的安装、配置与工具全景【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本文是一份面向开发者的实战指南系统讲解 MCP Toolbox 仓库中Cloud SQL for PostgreSQL MCP Server的完整用法从前置条件、安装步骤、环境变量配置到 20 个内置工具的归类与底层实现原理帮助你把 AI 编程助手接入 Google Cloud SQL for PostgreSQL 实例实现查询数据、探索 Schema、监控性能、管理扩展等能力。读完本文你将掌握该 MCP Server 的标准接入流程与可复用的配置模板。什么是 Cloud SQL for PostgreSQL MCP ServerCloud SQL for PostgreSQL MCP Server 是一个基于 Model Context ProtocolMCP的服务端实现让支持 MCP 的 AI 开发工具如 Antigravity、Gemini CLI 等能够直接操作你的 Google Cloud SQL for PostgreSQL 数据库。它内置的连接与工具层支持连接实例、探索 Schema、执行查询、分析性能并将这些能力以标准 MCP 工具的形式暴露给 AI 助手。该 Server 的预置配置位于仓库的 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml其中同时声明了三个底层 sourcecloud-sql-postgres数据库源、cloud-sql-admin管理源、cloud-monitoring监控源和按分组组织的全部工具。核心能力与典型场景配置完成后AI 助手可以直接理解并执行以下类型的自然语言请求查询数据执行 SQL 查询并生成 JSON 格式的 EXPLAIN 执行计划探索 Schema列出表、视图、索引、触发器、序列、存储过程与 Schema监控性能查看活动查询、表膨胀bloat、锁、长事务、内存配置与系统级 PromQL 指标管理扩展列出可安装与已安装的 PostgreSQL 扩展典型对话示例Show me the top 5 bloated tables. List all installed extensions. Explain the query plan for SELECT * FROM users.需要说明的是本文档聚焦数据库数据面的使用如果你还需要创建实例、克隆环境等 Cloud SQL 基础设施管理能力可以配合仓库中的 Cloud SQL for PostgreSQL Admin MCP Server 一起使用。前置条件在安装前请确认以下条件已满足Node.js已安装用于通过npx运行 MCP Toolbox。一个Google Cloud 项目并且已启用Cloud SQL Admin API。环境中可用的Application Default CredentialsADC。从源码看Cloud SQL 源默认通过 Cloud SQL Go Connector 中的initCloudSQLPgConnectionPool。IAM 权限至少具备Cloud SQL Clientroles/cloudsql.client角色数据库层面还需要相应的SELECT、INSERT等权限才能执行查询。注意如果你的实例使用私网 IPMCP Server 必须运行在同一个 VPC 网络中才能建立连接。安装与配置方式一通过 Antigravity MCP Store 安装在 Antigravity MCP Store 中点击 “Install” 按钮。首次使用时安装过程会自动下载并使用 MCP Toolboxtoolbox-sdk/server要求0.26.0。如需手动更新到最新版npm i -g toolbox-sdk/serverlatest若希望始终运行最新版本可将 MCP server 配置改为npx -y toolbox-sdk/serverlatest --prebuilt cloud-sql-postgres在配置弹窗中填写实例所需信息项目、区域、实例、数据库等点击 “Save”。之后可以随时在 “Configure” 页签中更新。配置完成后即可在 “Tools” 页签看到所有已启用的工具。提示如果 Windows Defender 拦截了执行需要为其配置排除项allowlist相关配置方法见 Microsoft Defender 官方文档。方式二手动编写 MCP 客户端配置MCP Server 本身通过环境变量进行配置这是它对接各类 MCP 客户端Gemini CLI 的settings.json、Antigravity 的mcp_config.json等的统一方式。标准配置模板如下{ mcpServers: { cloud-sql-postgres: { command: npx, args: [-y, toolbox-sdk/server, --prebuilt, cloud-sql-postgres, --stdio], env: { CLOUD_SQL_POSTGRES_PROJECT: your-project-id, CLOUD_SQL_POSTGRES_REGION: your-region, CLOUD_SQL_POSTGRES_INSTANCE: your-instance-id, CLOUD_SQL_POSTGRES_DATABASE: your-database-name, CLOUD_SQL_POSTGRES_USER: your-username, CLOUD_SQL_POSTGRES_PASSWORD: your-password } } } }对应的环境变量导出方式bashexport CLOUD_SQL_POSTGRES_PROJECTyour-gcp-project-id export CLOUD_SQL_POSTGRES_REGIONyour-cloud-sql-region export CLOUD_SQL_POSTGRES_INSTANCEyour-cloud-sql-instance-id export CLOUD_SQL_POSTGRES_DATABASEyour-database-name export CLOUD_SQL_POSTGRES_USERyour-database-user # Optional export CLOUD_SQL_POSTGRES_PASSWORDyour-database-password # Optional export CLOUD_SQL_POSTGRES_IP_TYPEPUBLIC # Optional: PUBLIC, PRIVATE, PSC. Defaults to PUBLIC. export CLOUD_SQL_POSTGRES_READONLYtrue # Optional: Restricts tools and enforces read-only session locking on the database connection. Defaults to false.环境变量与参数详解下表汇总了所有配置项及其语义对应预置配置 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml 与源码Config结构体字段环境变量对应 YAML 字段必填说明CLOUD_SQL_POSTGRES_PROJECTproject是GCP 项目 IDCLOUD_SQL_POSTGRES_REGIONregion是Cloud SQL 实例所在区域如us-central1CLOUD_SQL_POSTGRES_INSTANCEinstance是Cloud SQL 实例 IDCLOUD_SQL_POSTGRES_DATABASEdatabase是要连接的数据库名CLOUD_SQL_POSTGRES_USERuser否数据库用户名留空则使用 IAM 认证CLOUD_SQL_POSTGRES_PASSWORDpassword否数据库用户密码留空则尝试 IAM 认证CLOUD_SQL_POSTGRES_IP_TYPEipType否public、private或psc默认publicCLOUD_SQL_POSTGRES_READONLYreadOnly否设为true时强制数据库会话级只读并抑制写工具默认false预置 YAML 中使用${ENV_NAME}形式做环境变量占位替换例如kind: source name: cloudsql-pg-source type: cloud-sql-postgres project: ${CLOUD_SQL_POSTGRES_PROJECT} region: ${CLOUD_SQL_POSTGRES_REGION} instance: ${CLOUD_SQL_POSTGRES_INSTANCE} database: ${CLOUD_SQL_POSTGRES_DATABASE} user: ${CLOUD_SQL_POSTGRES_USER:} password: ${CLOUD_SQL_POSTGRES_PASSWORD:} ipType: ${CLOUD_SQL_POSTGRES_IP_TYPE:public} readOnly: ${CLOUD_SQL_POSTGRES_READONLY:false}工具能力总览Cloud SQL for PostgreSQL MCP Server 提供了以下工具README 清单与预置配置一一对应Tool NameDescriptionexecute_sql执行 SQLlist_tables列出用户创建表的详细 Schema 信息list_active_queries列出当前正在运行的 Top N 查询list_available_extensions发现所有可安装的 PostgreSQL 扩展list_installed_extensions列出所有已安装的 PostgreSQL 扩展list_autovacuum_configurations列出 autovacuum 相关配置list_memory_configurations列出内存相关配置list_top_bloated_tables按死元组近似膨胀信号列出 Top 表list_replication_slots列出所有复制槽的关键细节list_invalid_indexes列出所有无效的 PostgreSQL 索引get_query_plan以 JSON 格式生成 EXPLAIN 执行计划list_views列出数据库中的视图list_schemas列出数据库中的所有 Schemadatabase_overview获取 PostgreSQL 服务器当前状态list_triggers列出所有非内部触发器list_indexes列出数据库中的用户索引list_sequences列出数据库中的序列define_spec为搜索负载定义新的向量规格modify_spec修改现有向量规格apply_spec执行向量规格的 SQL 推荐generate_query为向量搜索生成优化的 SQL 查询list_specs列出指定表和列的向量规格get_spec按唯一 ID 获取向量规格delete_spec按唯一 ID 删除向量规格improve_query_recall改进向量搜索工作负载的查询召回率工具的隐藏扩展预置配置中的完整清单值得注意README 只列了 25 个工具但仓库的预置配置 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml 实际注册了更多工具包括long_running_transactions、list_locks、replication_stats、list_query_stats、get_column_cardinality、list_table_stats、list_publication_tables、list_tablespaces、list_pg_settings、list_database_stats、list_roles、list_stored_procedure、list_databases、create_backup、postgres_upgrade_precheck、create_instance、wait_for_operation、get_system_metrics、restore_backup、list_instances、create_database、create_user、get_query_metrics、clone_instance、get_instance等覆盖管理、生命周期、数据、监控、健康、视图配置、复制、向量检索八大分组。工具分组与使用建议预置配置通过kind: group对工具进行了场景化分组AI 助手可根据用户意图选择合适的工具组合admin实例运维create_instance、get_instance、list_instances、create_database、list_databases、create_user、wait_for_operation、clone_instancelifecycle备份与恢复create_backup、restore_backup、postgres_upgrade_precheck、wait_for_operation、database_overviewdata数据探索与执行execute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_proceduremonitor性能排查get_system_metrics、get_query_metrics、list_query_stats、get_query_plan、list_database_stats、list_active_queries、long_running_transactions、list_lockshealth健康审计list_top_bloated_tables、list_invalid_indexes、list_table_stats、get_column_cardinality、list_autovacuum_configurations、list_tablespaces、list_pg_settingsview-config扩展与引擎配置list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settingsreplication复制与安全replication_stats、list_replication_slots、list_publication_tables、list_rolesvectorassist向量工作负载define_spec、modify_spec、apply_spec、generate_query、improve_query_recall、list_specs、get_spec、delete_spec关键工具的底层实现剖析execute_sql 与 RunSQL 调用链execute_sql工具的底层执行由 internal/sources/cloudsqlpg/cloud_sql_pg.go 中的RunSQL方法完成。它通过pgxpool.Pool执行语句将结果按列名组织为有序 Map 返回并在执行前通过sqlcommenter.PrependComment自动附加 SQL 注释由sqlCommenter配置控制。这意味着所有查询都会带上可观测性的标注信息。list_top_bloated_tables基于 pg_stat_user_tables 的膨胀信号该工具postgres-sql类型执行如下 SQL按死元组降序排列并通过limit参数默认 50控制返回条数SELECT schemaname AS schema_name, relname AS relation_name, n_live_tup AS live_tuples, n_dead_tup AS dead_tuples, TRUNC((n_dead_tup::NUMERIC / NULLIF(n_live_tup n_dead_tup, 0)) * 100, 2) AS dead_tuple_percentage, last_vacuum, last_autovacuum, last_analyze, last_autoanalyze FROM pg_stat_user_tables ORDER BY n_dead_tup DESC LIMIT COALESCE($1::int, 50);get_query_plan不执行语句的 EXPLAIN该工具使用模板参数query生成 JSON 格式执行计划不会真正执行查询EXPLAIN (FORMAT JSON) {{.query}};预置配置中特别标注该工具存在 SQL 注入风险不要在生产环境使用。连接池、IAM 认证与只读模式从源码实现可以梳理出以下关键行为连接方式选择getConnectionConfig中若user与password同时提供则使用密码认证若两者都留空则从 ADC 获取 IAM 主体邮箱GetIAMPrincipalEmailFromADC(ctx, postgres)以 IAM 身份登录若只提供密码而没有用户名会直接报错要求两者同时提供或同时留空。连接池通过pgxpool.NewWithConfig创建连接池并配置DialFunc调用 Cloud SQL Go Connector 的Dial连接标识为project:region:instance格式。只读模式当readOnly为true时会在 DSN 中追加options-c cloudsql_session_read_onlylocked。源码注释特别提醒这里必须使用下划线cloudsql_session_read_only而不是点号cloudsql.session_read_only否则 PostgreSQL 会将其当作自定义占位符而静默忽略导致会话实际仍是读写模式。同时只读模式下会抑制写能力的工具。IP 类型校验internal/sources/ip_type.go 中的UnmarshalYAML只接受public、private、psc三种取值大小写不敏感默认public。非法值会在配置解析阶段即报错例如ipType invalid: must be one of public, private, or psc该错误信息也出现在 internal/sources/cloudsqlpg/cloud_sql_pg_test.go 的测试用例中。认证方式IAM 还是密码Cloud SQL for PostgreSQL 源同时支持两种认证标准认证在配置中提供user和password字段。IAM 认证一种方式是显式指定 IAM 邮箱作为user另一种方式是让user留空由 Toolbox 自动从 ADC 获取邮箱登录。IAM 认证时password留空。完整参考示例以下是手动编写 MCP 客户端配置的完整形态含可选参数{ mcpServers: { cloud-sql-postgres: { command: npx, args: [-y, toolbox-sdk/server, --prebuilt, cloud-sql-postgres, --stdio], env: { CLOUD_SQL_POSTGRES_PROJECT: my-project-id, CLOUD_SQL_POSTGRES_REGION: us-central1, CLOUD_SQL_POSTGRES_INSTANCE: my-instance, CLOUD_SQL_POSTGRES_DATABASE: my_db, CLOUD_SQL_POSTGRES_USER: my-pg-user, CLOUD_SQL_POSTGRES_PASSWORD: my-password, CLOUD_SQL_POSTGRES_IP_TYPE: PUBLIC, CLOUD_SQL_POSTGRES_READONLY: true } } } }对应的底层 source 配置YAML可参考 internal/prebuiltconfigs/tools/cloud-sql-postgres.yaml 以及文档 docs/en/integrations/cloud-sql-pg/source.md 中的参数参考表type、project、region、instance、database为必填user、password、ipType、readOnly、sqlCommenter为可选。运维注意事项私网实例ipTypeprivate时必须在同一 VPC 内运行所有连接无论公私网均基于 IAM 授权并经过 mTLS 加密。只读锁定如需防止 AI 助手误写数据务必设置CLOUD_SQL_POSTGRES_READONLYtrue它会同时在工具层抑制写工具与数据库会话层cloudsql_session_read_onlylocked双重生效。版本更新MCP Toolbox 首次安装要求0.26.0可通过npm i -g toolbox-sdk/serverlatest升级。源码验证如需深入阅读实现与测试可查看 internal/sources/cloudsqlpg/cloud_sql_pg.go、internal/sources/cloudsqlpg/cloud_sql_pg_test.go、internal/sources/ip_type.go以及集成测试 tests/cloudsqlpg/cloud_sql_pg_integration_test.go 与 tests/cloudsqlpg/cloud_sql_pg_upgrade_precheck_test.go。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考