MCP Toolbox for Databases 的 PostgreSQL 预构建配置完全指南环境变量、权限与 30 余个内置诊断工具详解【免费下载链接】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以下简称 Toolbox为 PostgreSQL 提供的预构建配置Prebuilt Configuration。通过一个--prebuilt postgres参数即可在 MCP 客户端中快速接入 PostgreSQL 数据源获得涵盖 SQL 执行、表结构查询、性能监控、复制状态、锁与长事务诊断在内的 30 余个现成工具无需手写任何 YAML 配置。读完本文你将掌握该预构建配置的完整环境变量清单、权限要求、每个工具的用途与实现方式以及如何在 Claude Code、Cursor、VS CodeCopilot等主流 MCP 客户端中一键启用。一、什么是预构建配置一条命令接入 PostgreSQLToolbox 提供了一组开箱即用的预构建配置将数据源连接与工具定义打包成一份内置 YAML。官方文档 docs/en/integrations/postgres/prebuilt-configs/postgresql.md 指出PostgreSQL 预构建配置对应的启动参数为--prebuilt postgres从源码看预构建配置通过 Go 的embed机制打包进二进制。在 internal/prebuiltconfigs/prebuiltconfigs.go 中//go:embed tools/*.yaml将internal/prebuiltconfigs/tools/目录下所有 YAML 文件嵌入运行时其中就包括 internal/prebuiltconfigs/tools/postgres.yaml。--prebuilt参数可以指定多次例如同时启用 PostgreSQL 与 MySQL它属于构建期build-time使用场景官方在 cmd/internal/options.go 中会打印明确警告这些预构建配置面向Agent 帮助受信任的开发者构建应用的场景其安全性不足以支撑运行时run-time面对不可信用户的场景。如果你希望只启用部分能力可以使用--prebuilt postgres/toolset语法限定工具集toolset例如--prebuilt postgres/monitor。该格式在 cmd/internal/options.go 中解析若指定的 toolset 不存在会直接报错并列出可用选项cmd/internal/options_test.go 的测试用例验证了这一行为toolset invalid-toolset not found in prebuilt configuration postgres. Available toolsets: data, health, monitor, replication, view-config注意--prebuilt postgres.sql、postgres:sql、postgressql这类写法都会被视为非法格式并报错提示请使用/指定 toolset见 cmd/internal/options_test.go。二、连接参数六种环境变量与默认值预构建配置通过环境变量向 Toolbox 传递连接信息全部变量定义在 internal/prebuiltconfigs/tools/postgres.yaml 中映射到名为postgresql-source的 source 上环境变量是否必需默认值说明POSTGRES_HOST可选localhostPostgreSQL 服务器的主机名或 IP 地址POSTGRES_PORT可选5432PostgreSQL 服务器的端口号POSTGRES_DATABASE必需无要连接的数据库名POSTGRES_USER必需无数据库用户名POSTGRES_PASSWORD必需无数据库用户密码POSTGRES_QUERY_PARAMS可选空追加到数据库连接字符串的原始查询参数对应的 YAML 片段如下kind: source name: postgresql-source type: postgres host: ${POSTGRES_HOST:localhost} port: ${POSTGRES_PORT:5432} database: ${POSTGRES_DATABASE} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD} queryParams: ${POSTGRES_QUERY_PARAMS:}这里的${ENV:default}语法表示取环境变量值未设置时使用冒号后的默认值。因此即便不设置POSTGRES_HOST和POSTGRES_PORTToolbox 也会默认连接本机localhost:5432——这对本地开发非常友好。POSTGRES_QUERY_PARAMS常用于追加sslmoderequire之类的连接级参数它对应 source 配置中的queryParams字段类型为map[string]string详见 docs/en/integrations/postgres/source.md。2.1 自定义连接时的扩展字段如果不用预构建配置而改用自定义 YAMLPostgreSQL source 还支持以下扩展字段见 docs/en/integrations/postgres/source.mdqueryExecModestring可选pgx 查询执行模式合法值包括cache_statement默认、cache_describe、describe_exec、exec、simple_protocol在连接池不支持预处理语句缓存时非常有用sqlCommenterboolean可选覆盖全局--sql-commenter标志配置后优先于全局设置connectTimeoutinteger可选单次连接尝试的最大等待秒数最小 1例如 5省略时不设超时。2.2 权限要求预构建配置本身不要求超级用户权限只需数据库层面的常规权限即可完成查询类工作。官方文档明确执行查询需要数据库级权限例如SELECT、INSERT。如果你还需要执行 DDL 或写入操作则需为相应数据库用户授予对应的数据库级权限。这一点与 docs/en/integrations/postgres/source.md 的说明一致该 source 仅使用标准认证你需要先创建一个可登录的 PostgreSQL 用户。三、工具全景30 余个内置工具的分类与实现预构建配置在 source 之上注册了 30 余个工具。下表完整列出官方文档 postgresql.md 中的全部工具并补充其底层类型与主要用途工具名底层实现用途execute_sqlpostgres-execute-sql执行单条 SQL 语句list_tablespostgres-list-tables列出用户表及详细 schema 信息对象类型、列、约束、索引、触发器、属主、注释list_active_queriespostgres-list-active-queries列出当前正在运行stateactive的 Top N 查询按运行时长倒序list_available_extensionspostgres-list-available-extensions发现服务器上可安装的所有 PostgreSQL 扩展list_installed_extensionspostgres-list-installed-extensions列出所有已安装扩展名称、版本、schema、属主、描述long_running_transactionspostgres-long-running-transactions识别并列出超过指定时长的事务list_lockspostgres-list-locks识别活跃进程持有的所有锁replication_statspostgres-replication-stats列出每个副本的进程 ID 与同步状态list_autovacuum_configurationspostgres-sql列出 autovacuum 相关配置来自 pg_settingslist_memory_configurationspostgres-sql列出内存相关配置work_mem、shared_buffers 等list_top_bloated_tablespostgres-sql按死元组占比列出最膨胀的表list_replication_slotspostgres-sql列出复制槽及其阻止回收的 WAL 大小list_invalid_indexespostgres-sql列出失效索引通常由失败的 CREATE INDEX CONCURRENTLY 产生get_query_planpostgres-sql生成 SQL 语句的 EXPLAIN JSON 执行计划不实际执行list_viewspostgres-list-views从 pg_views 列出视图默认上限 50 行返回 schema、view 名与属主list_schemaspostgres-list-schemas列出数据库中的 schemadatabase_overviewpostgres-database-overview获取 PostgreSQL 服务器当前状态list_triggerspostgres-list-triggers列出数据库中的触发器list_indexespostgres-list-indexes列出数据库中的用户索引list_sequencespostgres-list-sequences列出数据库中的序列list_query_statspostgres-list-query-stats列出查询统计信息get_column_cardinalitypostgres-get-column-cardinality获取列基数list_table_statspostgres-list-table-stats列出表统计信息list_publication_tablespostgres-list-publication-tables列出发布publication中的表list_tablespacespostgres-list-tablespaces列出表空间list_pg_settingspostgres-list-pg-settings列出 PostgreSQL 服务器配置参数list_database_statspostgres-list-database-stats列出每个数据库的关键性能与活动统计list_rolespostgres-list-roles列出所有用户创建的角色list_stored_procedurepostgres-list-stored-procedure列出存储过程3.1 实现上的两种工具形态从上表可以看到这 30 余个工具在 internal/prebuiltconfigs/tools/postgres.yaml 中由两种方式定义专用工具类型如postgres-list-tables、postgres-list-locks、postgres-long-running-transactions、postgres-replication-stats等对应 internal/tools/postgres/ 目录下独立的 Go 包每个包包含实现与测试文件。以postgres-list-tables为例其实现位于 internal/tools/postgres/postgreslisttables/postgreslisttables.go并配有完整测试。postgres-sql通用 SQL 工具如list_autovacuum_configurations、list_memory_configurations、list_top_bloated_tables、list_replication_slots、list_invalid_indexes、get_query_plan直接在预构建 YAML 中内嵌查询语句。例如list_autovacuum_configurations的完整定义就是一条针对pg_settings的分类查询kind: tool name: list_autovacuum_configurations type: postgres-sql source: postgresql-source description: List PostgreSQL autovacuum-related configurations (name and current setting) from pg_settings. statement: | SELECT name, setting FROM pg_settings WHERE category Autovacuum;这种配置即代码的设计让社区可以轻松扩展新的诊断工具只需要往 YAML 中添加一条带statement的工具定义。3.2 值得关注的诊断类工具细节list_top_bloated_tables基于pg_stat_user_tables统计死元组占比n_dead_tup / (n_live_tup n_dead_tup)并返回最近 vacuum/analyze 时间帮助你判断表是否需要手动 VACUUM。它还带有一个limit参数默认 50。list_replication_slots查询pg_replication_slots并通过pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)计算每个复制槽当前阻止回收的 WAL 大小retained_wal是排查 WAL 堆积问题的直接抓手。list_invalid_indexes查询pg_index中indisvalid FALSE的索引并给出索引大小与完整定义。此类索引通常由失败的CREATE INDEX CONCURRENTLY产生占磁盘空间却无法被查询规划器使用。get_query_plan生成EXPLAIN (FORMAT JSON)执行计划且不执行语句可用于成本与行数预估。官方在 YAML 描述中特别警告该工具存在 SQL 注入风险不要在生产环境使用见 internal/prebuiltconfigs/tools/postgres.yaml。list_memory_configurations将pg_settings中的内存参数统一换算为可读大小pg_size_prettywork_mem、maintenance_work_mem按 KB 换算shared_buffers、wal_buffers等按页8KB换算后展示。3.3 五大内置工具集Toolset为方便按需启用预构建 YAML 末尾将上述工具归入 5 个工具集见 internal/prebuiltconfigs/tools/postgres.yamldata数据读写与结构浏览含execute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_proceduremonitor运行时监控含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、database_overview、list_pg_settingsview-config配置检视含list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settings、database_overviewreplication复制与高可用含replication_stats、list_replication_slots、list_publication_tables、list_roles、list_pg_settings、database_overview。不指定工具集时默认启用全部工具指定时如--prebuilt postgres/monitor仅加载对应工具集这在权限最小化或降低模型上下文负担时非常实用。四、客户端接入实战Claude Code / Cursor / VS Code / Gemini CLI 等八种配置Toolbox 官方提供了与各主流 MCP 客户端对接的完整指南 docs/en/documentation/connect-to/ides/postgres_mcp.md覆盖 Claude Code、Claude Desktop、Cline、Cursor、VS CodeCopilot、Windsurf、Gemini CLI、Gemini Code Assist 共 8 个客户端。核心配置模式完全一致command指向 toolbox 二进制args传入--prebuilt postgres --stdioenv填入第二节的环境变量。4.1 启动前的准备创建或选择一个 PostgreSQL 实例本地安装或 AlloyDB Omni 均可创建/复用数据库用户并准备好用户名与密码下载对应平台的 Toolbox 二进制要求 V0.6.0chmod x toolbox后执行./toolbox --version验证安装。4.2 Claude Code 配置示例在项目根目录创建.mcp.json{ mcpServers: { postgres: { command: ./PATH/TO/toolbox, args: [--prebuilt,postgres,--stdio], env: { POSTGRES_HOST: , POSTGRES_PORT: , POSTGRES_DATABASE: , POSTGRES_USER: , POSTGRES_PASSWORD: } } } }保存后重启 Claude Code 即可生效。其中--stdio表示以标准输入输出方式与 MCP 客户端通信。4.3 其他客户端的差异点Claude Desktop在 Settings Developer 中编辑配置文件重启后可在聊天界面看到 MCP 锤子图标Cline在 VS Code 扩展的 MCP Servers 中配置连接成功显示绿色 active 状态Cursor在.cursor/mcp.json中配置成功后可在 Settings Cursor Settings MCP 看到绿色状态VS CodeCopilot在.vscode/mcp.json中配置注意其顶层键是servers而非mcpServersWindsurf在 Cascade 助手的 MCP 配置中填写同样的 JSONGemini CLI / Gemini Code Assist在工作目录的.gemini/settings.json中配置Code Assist 需先在扩展中启用 Agent Mode。4.4 验证与使用连接成功后直接向 AI 助手提问即可触发工具调用例如列出数据库中的表调用list_tables、创建一个新表调用execute_sql、有没有长时间运行的事务调用long_running_transactions。官方同时提示预构建工具仍处于 pre-1.0 阶段版本之间工具可能有变动但 LLM 会自动适应当前可用的工具集对大多数用户影响不大见 docs/en/documentation/connect-to/ides/postgres_mcp.md。五、权限与安全最佳实践结合官方文档与源码使用 PostgreSQL 预构建配置时有几点安全建议最小权限原则日常只读诊断场景为 Toolbox 创建仅具备SELECT等数据库级权限的专用账号避免使用超级用户善用工具集裁剪通过--prebuilt postgres/toolset只暴露所需工具减少攻击面与模型上下文占用明确使用边界预构建配置面向受信任开发者 Agent 辅助构建场景不应用于面向不可信用户的运行时服务见 cmd/internal/options.go 中的官方警告get_query_plan等工具存在 SQL 注入风险严禁在生产直接暴露避免硬编码密钥官方建议在自定义配置中使用${ENV_NAME}环境变量替换而非将密码写入配置文件见 docs/en/integrations/postgres/source.md预构建配置本身即遵循此模式。六、扩展阅读预构建配置完整定义含全部工具与工具集internal/prebuiltconfigs/tools/postgres.yamlPostgreSQL source 配置字段参考docs/en/integrations/postgres/source.md各 MCP 客户端接入指南docs/en/documentation/connect-to/ides/postgres_mcp.md预构建配置加载与解析实现internal/prebuiltconfigs/prebuiltconfigs.go、cmd/internal/options.go单个工具的源码与测试示例internal/tools/postgres/如postgreslisttables、postgreslongrunningtransactions、postgreslistlocks、postgresreplicationstats等工具清单文档docs/en/integrations/postgres/tools/postgres-execute-sql.md 及tools/目录下其余 20 余篇工具页【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MCP Toolbox for Databases 的 PostgreSQL 预构建配置完全指南：环境变量、权限与 30 余个内置诊断工具详解
MCP Toolbox for Databases 的 PostgreSQL 预构建配置完全指南环境变量、权限与 30 余个内置诊断工具详解【免费下载链接】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以下简称 Toolbox为 PostgreSQL 提供的预构建配置Prebuilt Configuration。通过一个--prebuilt postgres参数即可在 MCP 客户端中快速接入 PostgreSQL 数据源获得涵盖 SQL 执行、表结构查询、性能监控、复制状态、锁与长事务诊断在内的 30 余个现成工具无需手写任何 YAML 配置。读完本文你将掌握该预构建配置的完整环境变量清单、权限要求、每个工具的用途与实现方式以及如何在 Claude Code、Cursor、VS CodeCopilot等主流 MCP 客户端中一键启用。一、什么是预构建配置一条命令接入 PostgreSQLToolbox 提供了一组开箱即用的预构建配置将数据源连接与工具定义打包成一份内置 YAML。官方文档 docs/en/integrations/postgres/prebuilt-configs/postgresql.md 指出PostgreSQL 预构建配置对应的启动参数为--prebuilt postgres从源码看预构建配置通过 Go 的embed机制打包进二进制。在 internal/prebuiltconfigs/prebuiltconfigs.go 中//go:embed tools/*.yaml将internal/prebuiltconfigs/tools/目录下所有 YAML 文件嵌入运行时其中就包括 internal/prebuiltconfigs/tools/postgres.yaml。--prebuilt参数可以指定多次例如同时启用 PostgreSQL 与 MySQL它属于构建期build-time使用场景官方在 cmd/internal/options.go 中会打印明确警告这些预构建配置面向Agent 帮助受信任的开发者构建应用的场景其安全性不足以支撑运行时run-time面对不可信用户的场景。如果你希望只启用部分能力可以使用--prebuilt postgres/toolset语法限定工具集toolset例如--prebuilt postgres/monitor。该格式在 cmd/internal/options.go 中解析若指定的 toolset 不存在会直接报错并列出可用选项cmd/internal/options_test.go 的测试用例验证了这一行为toolset invalid-toolset not found in prebuilt configuration postgres. Available toolsets: data, health, monitor, replication, view-config注意--prebuilt postgres.sql、postgres:sql、postgressql这类写法都会被视为非法格式并报错提示请使用/指定 toolset见 cmd/internal/options_test.go。二、连接参数六种环境变量与默认值预构建配置通过环境变量向 Toolbox 传递连接信息全部变量定义在 internal/prebuiltconfigs/tools/postgres.yaml 中映射到名为postgresql-source的 source 上环境变量是否必需默认值说明POSTGRES_HOST可选localhostPostgreSQL 服务器的主机名或 IP 地址POSTGRES_PORT可选5432PostgreSQL 服务器的端口号POSTGRES_DATABASE必需无要连接的数据库名POSTGRES_USER必需无数据库用户名POSTGRES_PASSWORD必需无数据库用户密码POSTGRES_QUERY_PARAMS可选空追加到数据库连接字符串的原始查询参数对应的 YAML 片段如下kind: source name: postgresql-source type: postgres host: ${POSTGRES_HOST:localhost} port: ${POSTGRES_PORT:5432} database: ${POSTGRES_DATABASE} user: ${POSTGRES_USER} password: ${POSTGRES_PASSWORD} queryParams: ${POSTGRES_QUERY_PARAMS:}这里的${ENV:default}语法表示取环境变量值未设置时使用冒号后的默认值。因此即便不设置POSTGRES_HOST和POSTGRES_PORTToolbox 也会默认连接本机localhost:5432——这对本地开发非常友好。POSTGRES_QUERY_PARAMS常用于追加sslmoderequire之类的连接级参数它对应 source 配置中的queryParams字段类型为map[string]string详见 docs/en/integrations/postgres/source.md。2.1 自定义连接时的扩展字段如果不用预构建配置而改用自定义 YAMLPostgreSQL source 还支持以下扩展字段见 docs/en/integrations/postgres/source.mdqueryExecModestring可选pgx 查询执行模式合法值包括cache_statement默认、cache_describe、describe_exec、exec、simple_protocol在连接池不支持预处理语句缓存时非常有用sqlCommenterboolean可选覆盖全局--sql-commenter标志配置后优先于全局设置connectTimeoutinteger可选单次连接尝试的最大等待秒数最小 1例如 5省略时不设超时。2.2 权限要求预构建配置本身不要求超级用户权限只需数据库层面的常规权限即可完成查询类工作。官方文档明确执行查询需要数据库级权限例如SELECT、INSERT。如果你还需要执行 DDL 或写入操作则需为相应数据库用户授予对应的数据库级权限。这一点与 docs/en/integrations/postgres/source.md 的说明一致该 source 仅使用标准认证你需要先创建一个可登录的 PostgreSQL 用户。三、工具全景30 余个内置工具的分类与实现预构建配置在 source 之上注册了 30 余个工具。下表完整列出官方文档 postgresql.md 中的全部工具并补充其底层类型与主要用途工具名底层实现用途execute_sqlpostgres-execute-sql执行单条 SQL 语句list_tablespostgres-list-tables列出用户表及详细 schema 信息对象类型、列、约束、索引、触发器、属主、注释list_active_queriespostgres-list-active-queries列出当前正在运行stateactive的 Top N 查询按运行时长倒序list_available_extensionspostgres-list-available-extensions发现服务器上可安装的所有 PostgreSQL 扩展list_installed_extensionspostgres-list-installed-extensions列出所有已安装扩展名称、版本、schema、属主、描述long_running_transactionspostgres-long-running-transactions识别并列出超过指定时长的事务list_lockspostgres-list-locks识别活跃进程持有的所有锁replication_statspostgres-replication-stats列出每个副本的进程 ID 与同步状态list_autovacuum_configurationspostgres-sql列出 autovacuum 相关配置来自 pg_settingslist_memory_configurationspostgres-sql列出内存相关配置work_mem、shared_buffers 等list_top_bloated_tablespostgres-sql按死元组占比列出最膨胀的表list_replication_slotspostgres-sql列出复制槽及其阻止回收的 WAL 大小list_invalid_indexespostgres-sql列出失效索引通常由失败的 CREATE INDEX CONCURRENTLY 产生get_query_planpostgres-sql生成 SQL 语句的 EXPLAIN JSON 执行计划不实际执行list_viewspostgres-list-views从 pg_views 列出视图默认上限 50 行返回 schema、view 名与属主list_schemaspostgres-list-schemas列出数据库中的 schemadatabase_overviewpostgres-database-overview获取 PostgreSQL 服务器当前状态list_triggerspostgres-list-triggers列出数据库中的触发器list_indexespostgres-list-indexes列出数据库中的用户索引list_sequencespostgres-list-sequences列出数据库中的序列list_query_statspostgres-list-query-stats列出查询统计信息get_column_cardinalitypostgres-get-column-cardinality获取列基数list_table_statspostgres-list-table-stats列出表统计信息list_publication_tablespostgres-list-publication-tables列出发布publication中的表list_tablespacespostgres-list-tablespaces列出表空间list_pg_settingspostgres-list-pg-settings列出 PostgreSQL 服务器配置参数list_database_statspostgres-list-database-stats列出每个数据库的关键性能与活动统计list_rolespostgres-list-roles列出所有用户创建的角色list_stored_procedurepostgres-list-stored-procedure列出存储过程3.1 实现上的两种工具形态从上表可以看到这 30 余个工具在 internal/prebuiltconfigs/tools/postgres.yaml 中由两种方式定义专用工具类型如postgres-list-tables、postgres-list-locks、postgres-long-running-transactions、postgres-replication-stats等对应 internal/tools/postgres/ 目录下独立的 Go 包每个包包含实现与测试文件。以postgres-list-tables为例其实现位于 internal/tools/postgres/postgreslisttables/postgreslisttables.go并配有完整测试。postgres-sql通用 SQL 工具如list_autovacuum_configurations、list_memory_configurations、list_top_bloated_tables、list_replication_slots、list_invalid_indexes、get_query_plan直接在预构建 YAML 中内嵌查询语句。例如list_autovacuum_configurations的完整定义就是一条针对pg_settings的分类查询kind: tool name: list_autovacuum_configurations type: postgres-sql source: postgresql-source description: List PostgreSQL autovacuum-related configurations (name and current setting) from pg_settings. statement: | SELECT name, setting FROM pg_settings WHERE category Autovacuum;这种配置即代码的设计让社区可以轻松扩展新的诊断工具只需要往 YAML 中添加一条带statement的工具定义。3.2 值得关注的诊断类工具细节list_top_bloated_tables基于pg_stat_user_tables统计死元组占比n_dead_tup / (n_live_tup n_dead_tup)并返回最近 vacuum/analyze 时间帮助你判断表是否需要手动 VACUUM。它还带有一个limit参数默认 50。list_replication_slots查询pg_replication_slots并通过pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)计算每个复制槽当前阻止回收的 WAL 大小retained_wal是排查 WAL 堆积问题的直接抓手。list_invalid_indexes查询pg_index中indisvalid FALSE的索引并给出索引大小与完整定义。此类索引通常由失败的CREATE INDEX CONCURRENTLY产生占磁盘空间却无法被查询规划器使用。get_query_plan生成EXPLAIN (FORMAT JSON)执行计划且不执行语句可用于成本与行数预估。官方在 YAML 描述中特别警告该工具存在 SQL 注入风险不要在生产环境使用见 internal/prebuiltconfigs/tools/postgres.yaml。list_memory_configurations将pg_settings中的内存参数统一换算为可读大小pg_size_prettywork_mem、maintenance_work_mem按 KB 换算shared_buffers、wal_buffers等按页8KB换算后展示。3.3 五大内置工具集Toolset为方便按需启用预构建 YAML 末尾将上述工具归入 5 个工具集见 internal/prebuiltconfigs/tools/postgres.yamldata数据读写与结构浏览含execute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_proceduremonitor运行时监控含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、database_overview、list_pg_settingsview-config配置检视含list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settings、database_overviewreplication复制与高可用含replication_stats、list_replication_slots、list_publication_tables、list_roles、list_pg_settings、database_overview。不指定工具集时默认启用全部工具指定时如--prebuilt postgres/monitor仅加载对应工具集这在权限最小化或降低模型上下文负担时非常实用。四、客户端接入实战Claude Code / Cursor / VS Code / Gemini CLI 等八种配置Toolbox 官方提供了与各主流 MCP 客户端对接的完整指南 docs/en/documentation/connect-to/ides/postgres_mcp.md覆盖 Claude Code、Claude Desktop、Cline、Cursor、VS CodeCopilot、Windsurf、Gemini CLI、Gemini Code Assist 共 8 个客户端。核心配置模式完全一致command指向 toolbox 二进制args传入--prebuilt postgres --stdioenv填入第二节的环境变量。4.1 启动前的准备创建或选择一个 PostgreSQL 实例本地安装或 AlloyDB Omni 均可创建/复用数据库用户并准备好用户名与密码下载对应平台的 Toolbox 二进制要求 V0.6.0chmod x toolbox后执行./toolbox --version验证安装。4.2 Claude Code 配置示例在项目根目录创建.mcp.json{ mcpServers: { postgres: { command: ./PATH/TO/toolbox, args: [--prebuilt,postgres,--stdio], env: { POSTGRES_HOST: , POSTGRES_PORT: , POSTGRES_DATABASE: , POSTGRES_USER: , POSTGRES_PASSWORD: } } } }保存后重启 Claude Code 即可生效。其中--stdio表示以标准输入输出方式与 MCP 客户端通信。4.3 其他客户端的差异点Claude Desktop在 Settings Developer 中编辑配置文件重启后可在聊天界面看到 MCP 锤子图标Cline在 VS Code 扩展的 MCP Servers 中配置连接成功显示绿色 active 状态Cursor在.cursor/mcp.json中配置成功后可在 Settings Cursor Settings MCP 看到绿色状态VS CodeCopilot在.vscode/mcp.json中配置注意其顶层键是servers而非mcpServersWindsurf在 Cascade 助手的 MCP 配置中填写同样的 JSONGemini CLI / Gemini Code Assist在工作目录的.gemini/settings.json中配置Code Assist 需先在扩展中启用 Agent Mode。4.4 验证与使用连接成功后直接向 AI 助手提问即可触发工具调用例如列出数据库中的表调用list_tables、创建一个新表调用execute_sql、有没有长时间运行的事务调用long_running_transactions。官方同时提示预构建工具仍处于 pre-1.0 阶段版本之间工具可能有变动但 LLM 会自动适应当前可用的工具集对大多数用户影响不大见 docs/en/documentation/connect-to/ides/postgres_mcp.md。五、权限与安全最佳实践结合官方文档与源码使用 PostgreSQL 预构建配置时有几点安全建议最小权限原则日常只读诊断场景为 Toolbox 创建仅具备SELECT等数据库级权限的专用账号避免使用超级用户善用工具集裁剪通过--prebuilt postgres/toolset只暴露所需工具减少攻击面与模型上下文占用明确使用边界预构建配置面向受信任开发者 Agent 辅助构建场景不应用于面向不可信用户的运行时服务见 cmd/internal/options.go 中的官方警告get_query_plan等工具存在 SQL 注入风险严禁在生产直接暴露避免硬编码密钥官方建议在自定义配置中使用${ENV_NAME}环境变量替换而非将密码写入配置文件见 docs/en/integrations/postgres/source.md预构建配置本身即遵循此模式。六、扩展阅读预构建配置完整定义含全部工具与工具集internal/prebuiltconfigs/tools/postgres.yamlPostgreSQL source 配置字段参考docs/en/integrations/postgres/source.md各 MCP 客户端接入指南docs/en/documentation/connect-to/ides/postgres_mcp.md预构建配置加载与解析实现internal/prebuiltconfigs/prebuiltconfigs.go、cmd/internal/options.go单个工具的源码与测试示例internal/tools/postgres/如postgreslisttables、postgreslongrunningtransactions、postgreslistlocks、postgresreplicationstats等工具清单文档docs/en/integrations/postgres/tools/postgres-execute-sql.md 及tools/目录下其余 20 余篇工具页【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
