Postgres-MCP 工具

概述

Postgres MCP Pro 是一个开源的模型上下文协议（MCP）服务器，旨在支持您和您的AI代理在整个开发过程中——从初始编码、测试和部署，到生产调优和维护。

Postgres MCP Pro 不仅仅是封装了一个数据库连接。

功能包括：

• 🔍 数据库健康 - 分析索引健康、连接利用率、缓冲缓存、vacuum健康、序列限制、复制延迟等。
• ⚡ 索引调优 - 使用工业级算法探索数千种可能的索引来找到最适合您工作负载的解决方案。
• 📈 查询计划 - 通过审查EXPLAIN计划并模拟假设索引的影响来验证和优化性能。
• 🧠 模式智能 - 基于对数据库模式的详细理解进行上下文感知的SQL生成。
• 🛡️ 安全SQL执行 - 可配置的访问控制，包括支持只读模式和安全SQL解析，使其既可用于开发也可用于生产。

Postgres MCP Pro 支持 标准输入/输出 (stdio) 和 服务器发送事件 (SSE) 传输方式，以适应不同的环境。

有关我们为什么构建Postgres MCP Pro的更多背景，请参阅 我们的发布博客文章。

演示

从不可用到闪电般快速

• 挑战： 我们使用AI助手生成了一个电影应用，但SQLAlchemy ORM代码运行得非常慢。
• 解决方案： 使用Postgres MCP Pro与Cursor，我们在几分钟内解决了性能问题。

我们做了什么：

• 🚀 解决了性能问题 - 包括ORM查询、索引和缓存
• 🛠️ 修复了一个损坏的页面 - 通过提示代理探索数据、修复查询并添加相关内容。
• 🧠 改进了顶级电影 - 通过探索数据并修复ORM查询以呈现更相关的结果。

请观看下方视频或阅读 逐个步骤。

快速开始

前提条件

在开始之前，请确保您具备以下条件：

1. 数据库的访问凭证。
2. Docker 或 Python 3.12 或更高版本。

访问凭证

您可以使用 psql 或图形用户界面工具（例如 pgAdmin）来确认您的访问凭证是否有效。

Docker 或 Python

选择使用 Docker 还是 Python 取决于您自己。
我们通常推荐使用 Docker，因为使用 Python 的用户可能会遇到更多与环境相关的问题。
然而，通常来说，使用您最熟悉的方法会更有意义。

安装

请选择以下方法之一来安装 Postgres MCP Pro：

方法 1：使用 Docker

拉取 Postgres MCP Pro MCP 服务器的 Docker 镜像。
该镜像包含了所有必要的依赖项，提供了一种在各种环境中可靠运行 Postgres MCP Pro 的方式。

docker pull crystaldba/postgres-mcp

方法 2：使用 Python

如果您已经安装了 pipx，可以使用以下命令安装 Postgres MCP Pro：

pipx install postgres-mcp

否则，可以使用 uv 来安装 Postgres MCP Pro：

uv pip install postgres-mcp

如果您需要安装 uv，请参阅 uv 安装说明。

配置您的 AI 助手

我们提供了配置 Claude Desktop 与 Postgres MCP Pro 的完整说明。
许多 MCP 客户端具有类似的配置文件，您可以根据所选客户端调整这些步骤。

Claude Desktop 配置

您需要编辑 Claude Desktop 的配置文件以添加 Postgres MCP Pro。
该文件的位置取决于您的操作系统：

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

您也可以通过 Claude Desktop 中的 Settings 菜单项找到配置文件。

接下来，您将编辑配置文件中的 mcpServers 部分。

如果您使用的是 Docker

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

Postgres MCP Pro Docker 镜像会自动将主机名 localhost 映射为容器内部可用的形式。

• MacOS/Windows: 自动使用 host.docker.internal
• Linux: 自动使用 172.17.0.1 或适当的主机地址

如果您使用的是 pipx

{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": [
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

如果您使用的是 uv

{
  "mcpServers": {
    "postgres": {
      "command": "uv",
      "args": [
        "run",
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

连接 URI

将 postgresql://... 替换为您自己的 Postgres 数据库连接 URI。

访问模式

Postgres MCP Pro 支持多种 访问模式，以便您可以控制 AI 代理对数据库执行的操作：

• 无限制模式：允许完全读写访问以修改数据和架构。适用于开发环境。
• 限制模式：仅限于只读事务，并对资源使用（目前仅指执行时间）施加限制。适用于生产环境。

要使用受限模式，请将上述配置示例中的 --access-mode=unrestricted 替换为 --access-mode=restricted。

其他 MCP 客户端

许多 MCP 客户端的配置文件与 Claude Desktop 类似，您可以根据需要调整上面的示例以适应您选择的客户端。

• 如果您使用的是 Cursor，可以通过 命令面板 导航到 Cursor 设置，然后打开 MCP 选项卡来访问配置文件。
• 如果您使用的是 Windsurf，可以通过 命令面板 导航到 打开 Windsurf 设置页面 来访问配置文件。
• 如果您使用的是 Goose，请运行 goose configure，然后选择 添加扩展。

SSE 传输

Postgres MCP Pro 支持 SSE 传输，这允许多个 MCP 客户端共享一个服务器，可能是远程服务器。要使用 SSE 传输，您需要使用 --transport=sse 选项启动服务器。

例如，使用 Docker 运行：

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

然后更新您的 MCP 客户端配置以调用 MCP 服务器。例如，在 Cursor 的 mcp.json 或 Cline 的 cline_mcp_settings.json 中，您可以这样设置：

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

对于 Windsurf，mcp_config.json 中的格式略有不同：

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "serverUrl": "http://localhost:8000/sse"
        }
    }
}

Postgres 扩展安装（可选）

为了启用索引调优和全面的性能分析，您需要在数据库上加载 pg_statements 和 hypopg 扩展。

• pg_statements 扩展允许 Postgres MCP Pro 分析查询执行统计信息。例如，这使它能够了解哪些查询运行缓慢或消耗了大量资源。
• hypopg 扩展允许 Postgres MCP Pro 在添加索引后模拟 Postgres 查询规划器的行为。

在 AWS RDS、Azure SQL 或 Google Cloud SQL 上安装扩展

如果您的 Postgres 数据库运行在云提供商管理的服务上，pg_statements 和 hypopg 扩展应该已经在系统上可用。在这种情况下，您可以使用具有足够权限的角色运行 CREATE EXTENSION 命令：

CREATE EXTENSION IF NOT EXISTS pg_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

在自管 Postgres 上安装扩展

如果您自己管理 Postgres 安装，可能需要进行额外的工作。在加载 pg_statements 扩展之前，必须确保其被列在 Postgres 配置文件的 shared_preload_libraries 中。hypopg 扩展也可能需要额外的系统级安装（例如，通过包管理器），因为它并不总是随 Postgres 一起提供。

使用示例

获取数据库健康概览

询问：

检查我的数据库健康状况并识别任何问题。

分析慢查询

询问：

我的数据库中最慢的查询是什么？我如何加快它们的速度？

获取加速建议

询问：

我的应用程序很慢。我怎样才能让它更快？

生成索引建议

询问：

分析我的数据库工作负载，并建议索引来提高性能。

优化特定查询

询问：

请帮我优化这个查询：SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.created_at > '2023-01-01';

MCP 服务器 API

MCP 标准定义了多种类型的端点：工具、资源、提示等。

Postgres MCP Pro 仅通过 MCP 工具提供功能。
我们选择这种方法是因为 MCP 客户端生态系统广泛支持 MCP 工具。
这与其他 Postgres MCP 服务器的方法形成对比，包括使用 MCP 资源来暴露模式信息的参考 Postgres MCP 服务器。

Postgres MCP Pro 工具：

工具名称	描述
list_schemas	列出 PostgreSQL 实例中所有可用的数据库模式。
list_objects	列出指定模式内的数据库对象（表、视图、序列、扩展）。
get_object_details	提供关于特定数据库对象的信息，例如表的列、约束和索引。
execute_sql	在数据库上执行 SQL 语句，在受限模式连接时具有只读限制。
explain_query	获取 SQL 查询的执行计划，描述 PostgreSQL 如何处理该查询，并公开查询规划器的成本模型。可以使用假设索引来调用以模拟添加索引后的行为。
get_top_queries	基于 pg_stat_statements 数据报告最慢的 SQL 查询（按总执行时间）。
analyze_workload_indexes	分析数据库工作负载以识别资源密集型查询，然后为这些查询推荐最优索引。
analyze_query_indexes	分析特定 SQL 查询列表（最多 10 个）并为它们推荐最优索引。
analyze_db_health	执行全面的健康检查，包括：缓冲区缓存命中率、连接健康状况、约束验证、索引健康状况（重复/未使用/无效）、序列限制以及 VACUUM 健康状况。

相关项目

Postgres MCP 服务器

• 查询 MCP。一个为 Supabase Postgres 设计的 MCP 服务器，具有三层安全架构并支持 Supabase 管理 API。
• PG-MCP。一个针对 PostgreSQL 的 MCP 服务器，提供灵活的连接选项、解释计划、扩展上下文等功能。
• 参考 PostgreSQL MCP 服务器。一个简单的 MCP 服务器实现，将模式信息作为 MCP 资源暴露，并执行只读查询。
• Supabase Postgres MCP 服务器。这个 MCP 服务器提供了 Supabase 管理功能，并由 Supabase 社区积极维护。
• Nile MCP 服务器。一个提供对 Nile 多租户 Postgres 服务管理 API 访问的 MCP 服务器。
• Neon MCP 服务器。一个提供对 Neon 无服务器 Postgres 服务管理 API 访问的 MCP 服务器。
• Wren MCP 服务器。为 Postgres 及其他数据库提供语义引擎，支持商业智能。

DBA 工具（包括商业产品）

• Aiven 数据库优化器。一个工具，提供全面的数据库工作负载分析、查询优化及其他性能改进。
• dba.ai。一款基于 AI 的数据库管理助手，与 GitHub 集成以解决代码问题。
• pgAnalyze。一个综合性的监控和分析平台，用于识别性能瓶颈、优化查询以及实时警报。
• Postgres.ai。结合了广泛的 Postgres 知识库与 GPT-4 的交互式聊天体验。
• Xata 代理。一个开源的 AI 代理，自动监控数据库健康状况，诊断问题，并使用 LLM 支持的推理和剧本提供建议。

Postgres 实用工具

• Dexter。一个用于生成和测试 PostgreSQL 假设索引的工具。
• PgHero。一个带有建议的 Postgres 性能仪表板。
  Postgres MCP Pro 结合了来自 PgHero 的健康检查。
• PgTune。调整 Postgres 配置的启发式方法。

常见问题解答

Postgres MCP Pro 与其他 Postgres MCP 服务器有何不同？
有许多 MCP 服务器允许 AI 代理对 Postgres 数据库运行查询。
Postgres MCP Pro 也支持这一点，但还增加了用于理解和改进 Postgres 数据库性能的工具。
例如，它实现了一个版本的 Microsoft SQL Server 的数据库调优顾问的 Anytime 算法，这是一种现代工业级的自动索引调优算法。

Postgres MCP Pro	其他 Postgres MCP 服务器
✅ 确定性的数据库健康检查	❌ 不可重复的 LLM 生成的健康查询
✅ 原则性索引搜索策略	❌ 生成式 AI 对索引改进的猜测
✅ 工作负载分析以发现主要问题	❌ 不一致的问题分析
✅ 模拟性能改进	❌ 自行尝试并查看是否有效

Postgres MCP Pro 通过增加确定性工具和经典优化算法来补充生成式 AI。
这种组合既可靠又灵活。

当 LLM 可以进行推理、生成 SQL 等时，为什么还需要 MCP 工具？
对于涉及模糊性、推理或自然语言的任务，LLM 是无价之宝。
然而，与过程代码相比，它们可能速度较慢、成本较高、非确定性，并且有时会产生不可靠的结果。
在数据库调优方面，我们有经过数十年发展验证有效的成熟算法。
Postgres MCP Pro 通过将 LLM 与经典优化算法和其他过程工具配对，让您能够结合两者的优点。

如何测试 Postgres MCP Pro？
测试对于确保 Postgres MCP Pro 的可靠性和准确性至关重要。
我们正在构建一套由 AI 生成的对抗性工作负载，旨在挑战 Postgres MCP Pro 并确保其在各种场景下都能表现良好。

支持哪些版本的 Postgres？
目前我们的测试重点是 Postgres 15、16 和 17。
我们计划支持 Postgres 13 至 17 版本。

谁创建了这个项目？
该项目由 Crystal DBA 创建和维护。

道路图

待定

您和您的需求是我们构建内容的关键驱动力。
通过打开一个 issue 或 pull request 来告诉我们您希望看到的内容。
您也可以通过 Discord 联系我们。

技术说明

本节包括影响 Postgres MCP Pro 设计的技术考虑的高级概述。

索引调优

开发者知道，缺少索引是导致数据库性能问题的最常见原因之一。
索引提供了访问方法，使Postgres能够快速定位执行查询所需的数据。
当表较小时，索引的影响不大，但随着数据量的增长，表扫描和索引查找之间的算法复杂度差异变得显著（通常是O(n)与O(log n)，如果涉及多个表的连接，可能会更大）。

在Postgres MCP Pro中生成建议的索引分为几个阶段：

1. Identify SQL queries in need of tuning.
   If you know you are having a problem with a specific SQL query you can provide it.
   Postgres MCP Pro can also analyze the workload to identify index tuning targets.
   To do this, it relies on the pg_stat_statements extension, which records the runtime and resource consumption of each query.

   A query is a candidate for index tuning if it is a top resource consumer, either on a per-execution basis or in aggregate.
   At present, we use execution time as a proxy for cumulative resource consumption, but it may also make sense to look at specifics resources, e.g., the number of blocks accessed or the number of blocks read from disk.
   The analyze_query_workload tool focuses on slow queries, using the mean time per execution with thresholds for execution count and mean execution time.
   Agents may also call get_top_queries, which accepts a parameter for mean vs. total execution time, then pass these queries analyze_query_indexes to get index recommendations.

   Sophisticated index tuning systems use "workload compression" to produce a representative subset of queries that reflects the characteristics of the workload as a whole, reducing the problem for downstream algorithms.
   Postgres MCP Pro performs a limited form of workload compression by normalizing queries so that those generated from the same template appear as one.
   It weights each query equally, a simplification that works when the benefits to indexing are large.

2. Generate candidate indexes
   Once we have a list of SQL queries that we want to improve through indexing, we generate a list of indexes that we might want to add.
   To do this, we parse the SQL and identify any columns used in filters, joins, grouping, or sorting.

   To generate all possible indexes we need to consider combinations of these columns, because Postgres supports multicolumn indexes.
   In the present implementation, we include only one permutation of each possible multicolumn index, which is selected at random.
   We make this simplification to reduce the search space because permutations often have equivalent performance.
   However, we hope to improve in this area.

3. Search for the optimal index configuration.
   Our objective is to find the combination of indexes that optimally balances the performance benefits against the costs of storing and maintaining those indexes.
   We estimate the performance improvement by using the "what if?" capabilities provided by the hypopg extension.
   This simulates how the Postgres query optimizer will execute a query after the addition of indexes, and reports changes based on the actual Postgres cost model.

   One challenge is that generating query plans generally requires knowledge of the specific parameter values used in the query.
   Query normalization, which is necessary to reduce the queries under consideration, removes parameter constants.
   Parameter values provided via bind variables are similarly not available to us.

   To address this problem, we produce realistic constants that we can provide as parameters by sampling from the table statistics.
   In version 16, Postgres added generic explain plan functionality, but it has limitations, for example around LIKE clauses, which our implementation does not have.

   Search strategy is critical because evaluating all possible index combinations feasible only in simple situations.
   This is what most sets apart various indexing approaches.
   Adapting the approach of Microsoft's Anytime algorithm, we employ a greedy search strategy, i.e., find the best one-index solution, then find the best index to add to that to produce a two-index solution.
   Our search terminates when the time budget is exhausted or when a round of exploration fails to produce any gains above the minimum improvement threshold of 10%.

4. Cost-benefit analysis.
   When posed with two indexing alternatives, one which produces better performance and one which requires more space, how do we decide which to choose?
   Traditionally, index advisors ask for a storage budget and optimize performance with respect to that storage budget.
   We also take a storage budget, but perform a cost-benefit analysis throughout the optimization.

   We frame this as the problem of selecting a point along the Pareto front—the set of choices for which improving one quality metric necessarily worsens another.
   In an ideal world, we might want to assess the cost of the storage and the benefit of improved performance in monetary terms.
   However, there is a simpler and more practical approach: to look at the changes in relative terms.
   Most people would agree that a 100x performance improvement is worth it, even if the storage cost is 2x.
   In our implementation, we use a configurable parameter to set this threshold.
   By default, we require the change in the log (base 10) of the performance improvement to be 2x the difference in the log of the space cost.
   This works out to allowing a maximum 10x increase in space for a 100x performance improvement.

我们的实现与在 Microsoft SQL Server 中发现的 Anytime Algorithm 最为相关。与 Dexter（一个用于 Postgres 的自动索引工具）相比，我们搜索的空间更大，并且使用了不同的启发式方法。这使得我们能够生成更好的解决方案，但代价是运行时间更长。

我们还展示了每次搜索轮次中完成的工作，包括在添加每个索引之前和之后的查询计划对比。这为大语言模型提供了额外的上下文，以便在响应索引建议时可以使用这些信息。

数据库健康

数据库健康检查能够在导致严重问题之前识别出调优机会和维护需求。在当前版本中，Postgres MCP Pro 直接从 PgHero 适应了数据库健康检查功能。我们正在努力全面验证这些检查，并可能在未来对其进行扩展。

• 索引健康。查找未使用的索引、重复的索引以及膨胀的索引。膨胀的索引会低效地使用数据库页面。
  Postgres 自动清理会清理指向死元组的索引条目，并将这些条目标记为可重用。但是，它不会压缩索引页，最终索引页可能只包含少量活跃元组引用。
• 缓冲区缓存命中率。衡量从缓冲区缓存而不是磁盘服务的数据库读取的比例。
  较低的缓冲区缓存命中率需要调查，因为它通常不是成本最优的，并且会导致应用程序性能下降。
• 连接健康。检查到数据库的连接数量及其使用情况。
  最大的风险是连接耗尽，但大量空闲或阻塞的连接也可能表明存在问题。
• Vacuum 健康。Vacuum 对于许多原因都很重要。
  其中一个关键原因是防止事务 ID 回绕，这可能导致数据库停止接受写入。
  Postgres 的多版本并发控制 (MVCC) 机制要求每个事务都有唯一的事务 ID。
  但是，由于 Postgres 使用 32 位有符号整数作为事务 ID，因此在最多 20 亿个事务后需要重用事务 ID。
  为此，它“冻结”历史事务的事务 ID，将它们全部设置为表示遥远过去的特殊值。
  当记录首次写入磁盘时，它们被写入可见性以供一系列事务 ID 使用。
  在重用这些事务 ID 之前，Postgres 必须更新任何磁盘上的记录，“冻结”它们以移除对要重用的事务 ID 的引用。
  此检查查找需要 vacuum 操作以防止事务 ID 回绕的表。
• 复制健康。通过监控主服务器和副本之间的滞后、验证复制状态以及跟踪复制槽的使用来检查复制健康状况。
• 约束健康。在正常操作期间，Postgres 会拒绝导致约束违反的所有事务。
  但是在加载数据或恢复场景后可能会出现无效约束。此检查查找任何无效约束。
• 序列健康。查找存在超过其最大值风险的序列。

Postgres 客户端库

Postgres MCP Pro 使用 psycopg3 通过异步 I/O 连接到 Postgres。
底层，psycopg3 使用 libpq 库连接到 Postgres，提供对完整 Postgres 功能集的访问，并且底层实现完全由 Postgres 社区支持。

一些基于 Python 的 MCP 服务器使用 asyncpg，这可能通过消除 libpq 依赖项来简化安装。
Asyncpg 可能比 psycopg3 更快，但这一点我们尚未亲自验证。
旧的基准测试 报告了更大的性能差距，表明随着 psycopg3 的成熟，这个差距已经缩小。

综合考虑这些因素，我们选择了 psycopg3 而不是 asyncpg。
我们对未来重新评估这一决定持开放态度。

连接配置

与 参考 PostgreSQL MCP 服务器 类似，Postgres MCP Pro 在启动时接受 Postgres 连接信息。
这对于总是连接到同一数据库的用户来说很方便，但对于需要切换数据库的用户来说可能会很麻烦。

另一种方法是像 PG-MCP 那样，在使用时通过 MCP 工具调用提供连接详情。
这对于需要切换数据库的用户来说更方便，并且允许单个 MCP 服务器同时支持多个最终用户。

一定有更好的方法可以替代这两种方法。
这两种方法都存在安全弱点——很少有 MCP 客户端能够安全地存储 MCP 服务器配置（Goose 是一个例外），并且通过 MCP 工具提供的凭据会通过 LLM 传递并存储在聊天历史中。
此外，在某些场景下，这两种方法都有可用性问题。

模式信息

模式信息工具的目的是为调用的 AI 代理提供生成正确且高效的 SQL 所需的信息。
例如，假设用户询问：“在过去的一年里，有多少航班从旧金山起飞并在巴黎降落？”
AI 代理需要找到存储航班的表、存储出发地和目的地的列，以及可能用于将机场代码映射到机场位置的表。

既然 LLM 通常能够直接从 Postgres 中检索此信息生成 SQL，为什么还要提供模式信息工具？

我们使用 Claude 的经验表明，调用的 LLM 非常擅长通过查询 Postgres 系统目录 和 信息模式（一种 ANSI 标准化的数据库元数据视图）来探索 Postgres 模式。
然而，我们不知道其他 LLM 是否同样可靠和有能力这样做。

使用 MCP 资源 而不是 MCP 工具 提供模式信息是否会更好？

参考 PostgreSQL MCP 服务器 使用资源来暴露模式信息，而不是使用工具。
浏览资源类似于浏览文件系统，因此在许多方面这种做法是很自然的。
然而，在 MCP 客户端生态系统中，资源支持不如工具支持广泛（参见示例客户端）。
此外，尽管 MCP 标准指出资源可以由 AI 代理或最终用户访问，但有些客户端仅支持最终用户浏览资源树。

受保护的 SQL 执行

AI 放大了长期以来保护数据库免受各种威胁的挑战，这些威胁从简单的错误到恶意行为者的复杂攻击不等。
无论是意外威胁还是恶意威胁，都适用类似的网络安全框架，其目标分为三类：机密性、完整性和可用性。
便利性和安全性之间的熟悉矛盾在这里也十分明显且突出。

Postgres MCP Pro 的受保护 SQL 执行模式侧重于完整性。
在 MCP 的上下文中，我们最关心的是 LLM 生成的 SQL 导致的损害——例如，无意的数据修改或删除，或其他可能绕过组织变更管理流程的更改。

提供完整性的最简单方法是确保所有针对数据库执行的 SQL 都是只读的。
实现这一点的一种方法是创建一个具有只读访问权限的数据库用户。
虽然这是一个好方法，但在实践中许多人发现这很麻烦。
Postgres 没有提供将连接或会话置于只读模式的方法，因此 Postgres MCP Pro 使用一种方法来……