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 Code（Copilot）等主流 MCP 客户端中一键启用。

一、什么是预构建配置：一条命令接入 PostgreSQL

Toolbox 提供了一组"开箱即用"的预构建配置，将"数据源连接"与"工具定义"打包成一份内置 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、postgres@sql这类写法都会被视为非法格式并报错提示"请使用/指定 toolset"（见 cmd/internal/options_test.go）。

二、连接参数：六种环境变量与默认值

预构建配置通过环境变量向 Toolbox 传递连接信息，全部变量定义在 internal/prebuiltconfigs/tools/postgres.yaml 中，映射到名为postgresql-source的 source 上：

对应的 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_PORT，Toolbox 也会默认连接本机localhost:5432——这对本地开发非常友好。POSTGRES_QUERY_PARAMS常用于追加sslmode=require之类的连接级参数，它对应 source 配置中的queryParams字段（类型为map[string]string），详见 docs/en/integrations/postgres/source.md。

2.1 自定义连接时的扩展字段

如果不用预构建配置而改用自定义 YAML，PostgreSQL source 还支持以下扩展字段（见 docs/en/integrations/postgres/source.md）：

• queryExecMode（string，可选）：pgx 查询执行模式，合法值包括cache_statement（默认）、cache_describe、describe_exec、exec、simple_protocol，在连接池不支持预处理语句缓存时非常有用；
• sqlCommenter（boolean，可选）：覆盖全局--sql-commenter标志，配置后优先于全局设置；
• connectTimeout（integer，可选）：单次连接尝试的最大等待秒数（最小 1，例如 5），省略时不设超时。

2.2 权限要求

预构建配置本身不要求超级用户权限，只需数据库层面的常规权限即可完成查询类工作。官方文档明确：执行查询需要数据库级权限（例如SELECT、INSERT）。如果你还需要执行 DDL 或写入操作，则需为相应数据库用户授予对应的数据库级权限。这一点与 docs/en/integrations/postgres/source.md 的说明一致：该 source 仅使用标准认证，你需要先创建一个可登录的 PostgreSQL 用户。

三、工具全景：30 余个内置工具的分类与实现

预构建配置在 source 之上注册了 30 余个工具。下表完整列出官方文档 postgresql.md 中的全部工具，并补充其底层类型与主要用途：

3.1 实现上的两种工具形态

从上表可以看到，这 30 余个工具在 internal/prebuiltconfigs/tools/postgres.yaml 中由两种方式定义：

1. 专用工具类型：如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，并配有完整测试。

2. 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_pretty），work_mem、maintenance_work_mem按 KB 换算，shared_buffers、wal_buffers等按页（8KB）换算后展示。

3.3 五大内置工具集（Toolset）

为方便按需启用，预构建 YAML 末尾将上述工具归入 5 个工具集（见 internal/prebuiltconfigs/tools/postgres.yaml）：

• data：数据读写与结构浏览，含execute_sql、list_tables、list_views、list_schemas、list_triggers、list_indexes、list_sequences、list_stored_procedure；
• monitor：运行时监控，含list_query_stats、get_query_plan、list_database_stats、list_active_queries、long_running_transactions、list_locks；
• health：健康与性能体检，含list_top_bloated_tables、list_invalid_indexes、list_table_stats、get_column_cardinality、list_autovacuum_configurations、list_tablespaces、database_overview、list_pg_settings；
• view-config：配置检视，含list_available_extensions、list_installed_extensions、list_memory_configurations、list_pg_settings、database_overview；
• replication：复制与高可用，含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 Code（Copilot）、Windsurf、Gemini CLI、Gemini Code Assist 共 8 个客户端。核心配置模式完全一致：command指向 toolbox 二进制，args传入--prebuilt postgres --stdio，env填入第二节的环境变量。

4.1 启动前的准备

1. 创建或选择一个 PostgreSQL 实例（本地安装或 AlloyDB Omni 均可）；
2. 创建/复用数据库用户并准备好用户名与密码；
3. 下载对应平台的 Toolbox 二进制（要求 V0.6.0+），chmod +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 Code（Copilot）：在.vscode/mcp.json中配置，注意其顶层键是servers而非mcpServers；
• Windsurf：在 Cascade 助手的 MCP 配置中填写同样的 JSON；
• Gemini 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 预构建配置时有几点安全建议：

1. 最小权限原则：日常只读诊断场景，为 Toolbox 创建仅具备SELECT等数据库级权限的专用账号，避免使用超级用户；
2. 善用工具集裁剪：通过--prebuilt postgres/<toolset>只暴露所需工具，减少攻击面与模型上下文占用；
3. 明确使用边界：预构建配置面向"受信任开发者 + Agent 辅助构建"场景，不应用于面向不可信用户的运行时服务（见 cmd/internal/options.go 中的官方警告）；get_query_plan等工具存在 SQL 注入风险，严禁在生产直接暴露；
4. 避免硬编码密钥：官方建议在自定义配置中使用${ENV_NAME}环境变量替换而非将密码写入配置文件（见 docs/en/integrations/postgres/source.md），预构建配置本身即遵循此模式。

六、扩展阅读

• 预构建配置完整定义（含全部工具与工具集）：internal/prebuiltconfigs/tools/postgres.yaml
• PostgreSQL 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