Postgres MCP

概述

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

Postgres MCP Pro 的作用远不止包装数据库连接。

功能包括：

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

Postgres MCP Pro 支持标准输入/输出 (stdio)和服务器发送事件 (SSE)传输，以便在不同环境中灵活使用。

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

演示

从无法使用到闪电般快速

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

我们做了什么：

• 🚀 修复性能问题 - 包括 ORM 查询、索引和缓存
• 🛠️ 修复了损坏的页面 - 通过提示代理探索数据、修复查询和添加相关内容。
• 🧠 改进了热门电影 - 通过探索数据和修复 ORM 查询来显示更多相关结果。

观看下面的视频或阅读详细内容。

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

快速入门

先决条件

在开始之前，请确保您已：

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

访问凭证

您可以使用psql或 GUI 工具（例如pgAdmin ）来确认您的访问凭据是否有效。

Docker 或 Python

使用 Docker 还是 Python，完全由您决定。我们通常推荐 Docker，因为 Python 用户可能会遇到更多特定于环境的问题。不过，通常情况下，选择您最熟悉的方法才是明智之举。

安装

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

选项 1：使用 Docker

拉取 Postgres MCP Pro MCP 服务器 Docker 镜像。此镜像包含所有必要的依赖项，可在各种环境中可靠地运行 Postgres MCP Pro。

选项 2：使用 Python

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

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

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

配置你的AI助手

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

Claude桌面配置

您需要编辑 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

Postgres MCP Pro Docker 镜像将自动重新映射主机名localhost以便在容器内部工作。

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

如果你使用pipx

如果你使用uv

连接 URI

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

访问模式

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

• 不受限制模式：允许完全读/写访问权限以修改数据和架构。适用于开发环境。
• 限制模式：将操作限制为只读事务，并对资源利用率施加限制（目前仅限制执行时间）。适用于生产环境。

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

其他 MCP 客户端

许多 MCP 客户端具有与 Claude Desktop 类似的配置文件，您可以调整上述示例以适合您选择的客户端。

• 如果您正在使用 Cursor，您可以从Command Palette导航到Cursor Settings ，然后打开MCP选项卡来访问配置文件。
• 如果您正在使用 Windsurf，您可以从Command Palette导航到Open Windsurf Settings Page来访问配置文件。
• 如果您使用 Goose 运行goose configure ，然后选择Add Extension 。

上交所运输

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

例如，使用 Docker 运行：

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

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

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命令即可：

在自管理 Postgres 上安装扩展

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

使用示例

获取数据库健康概览

问：

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

分析慢查询

问：

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

获取有关如何加快速度的建议

问：

我的应用运行缓慢。如何让它运行得更快？

生成索引建议

问：

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

优化特定查询

问：

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

MCP 服务器 API

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

Postgres MCP Pro 仅通过MCP 工具提供功能。我们之所以选择这种方式，是因为MCP 客户端生态系统对 MCP 工具提供了广泛的支持。这与其他 Postgres MCP 服务器（包括参考 Postgres MCP 服务器）的做法形成了鲜明对比，这些服务器使用MCP 资源来公开架构信息。

Postgres MCP Pro 工具：

相关项目

Postgres MCP 服务器

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

DBA 工具（包括商业产品）

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

Postgres 实用程序

• Dexter . 用于在 PostgreSQL 上生成和测试假设索引的工具。
• PgHero . Postgres 的性能仪表盘，提供建议。Postgres MCP Pro 集成了 PgHero 的健康检查功能。
• 用于调整 Postgres 配置的启发式方法。

常见问题

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

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

既然 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创建并维护。

路线图

待定

您和您的需求是我们构建产品的关键驱动力。请通过提交问题或拉取请求告诉我们您希望看到的内容。您也可以通过Discord联系我们。

技术说明

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

索引调整

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

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

1. 识别需要调优的 SQL 查询。如果您知道某个特定的 SQL 查询存在问题，您可以提供该问题。Postgres MCP Pro 还可以分析工作负载以确定索引调优目标。为此，它依赖于pg_stat_statements扩展，该扩展记录每个查询的运行时和资源消耗。如果查询是资源消耗最大的查询（无论是按每次执行还是按总体计算），则该查询可以作为索引调优的候选。目前，我们使用执行时间作为累积资源消耗的指标，但查看具体资源（例如访问的块数或从磁盘读取的块数）也可能有意义。analyze_query_workload 工具专注于慢速查询，使用每次执行的平均时间，并设置执行次数和平均执行时间get_top_queries``analyze_query_workload它接受一个表示平均执行时间与总执行时间的参数，然后将这些查询传递给analyze_query_indexes以获取索引建议。复杂的索引调优系统使用“工作负载压缩”来生成一个具有代表性的查询子集，该子集能够反映整体工作负载的特征，从而减少下游算法的计算量。Postgres MCP Pro 通过规范化查询来执行有限形式的工作负载压缩，使来自同一模板的查询看起来像一个查询。它对每个查询赋予相同的权重，这种简化方法在索引效益显著时非常有效。
2. 生成候选索引一旦我们有了想要通过索引改进的 SQL 查询列表，我们就会生成一个可能想要添加的索引列表。为此，我们需要解析 SQL 查询，并识别出在筛选、连接、分组或排序中使用的所有列。为了生成所有可能的索引，我们需要考虑这些列的组合，因为 Postgres 支持多列索引。在当前的实现中，我们只包含每个可能的多列索引的一个排列，并且是随机选择的。我们进行这种简化是为了缩小搜索空间，因为排列通常具有同等的性能。然而，我们希望在这方面有所改进。
3. 寻找最佳索引配置。我们的目标是找到在性能优势与存储和维护这些索引的成本之间实现最佳平衡的索引组合。我们使用hypopg扩展提供的“假设分析”功能来估算性能提升。该扩展模拟了 Postgres 查询优化器在添加索引后执行查询的方式，并根据实际的 Postgres 成本模型报告变化。一个挑战是，生成查询计划通常需要了解查询中使用的具体参数值。查询规范化对于减少查询数量至关重要，它会删除参数常量。同样，我们也无法获取通过绑定变量提供的参数值。为了解决这个问题，我们通过从表统计信息中抽样，生成了一些可以作为参数的实际常量。在 Postgres 16 版本中，它添加了通用的解释计划功能，但它存在一些限制，例如LIKE子句，而我们的实现没有这些限制。搜索策略至关重要，因为评估所有可能的索引组合仅在简单情况下可行。这正是各种索引方法之间的主要区别所在。我们借鉴微软 Anytime 算法，采用贪婪搜索策略，即先找到最佳的单索引解决方案，然后再找到最佳的索引添加到该解决方案中，从而得到双索引解决方案。当时间预算耗尽或一轮探索未能产生超过 10% 最低改进阈值的任何收益时，我们的搜索终止。
4. 成本效益分析。当面临两种索引方案时，一种性能更佳，另一种则需要更多空间，我们该如何选择？传统上，索引顾问会询问存储预算，并根据该预算优化性能。我们也会考虑存储预算，但会在整个优化过程中进行成本效益分析。我们将此问题定义为在帕累托前沿上选择一个点的问题——帕累托前沿是一组选择，对于这些选择，改善一个质量指标必然会导致另一个指标恶化。在理想情况下，我们可能希望以金钱形式评估存储成本和性能提升带来的好处。然而，有一种更简单、更实用的方法：从相对角度来看待变化。大多数人会同意，即使存储成本是 2 倍，100 倍的性能提升也是值得的。在我们的实现中，我们使用一个可配置参数来设置此阈值。默认情况下，我们要求性能提升的对数（以 10 为底）的变化量是空间成本对数差异的 2 倍。这意味着，性能提升 100 倍时，最多可以将空间增加 10 倍。

我们的实现与 Microsoft SQL Server 中的Anytime 算法最为接近。与 Postgres 的自动索引工具Dexter相比，我们的搜索范围更大，并使用了不同的启发式算法。这使我们能够以更长的运行时间为代价来生成更好的解决方案。

我们还展示了每轮搜索中完成的工作，包括添加每个索引前后查询计划的比较。这为 LLM 提供了额外的上下文，使其能够在响应索引建议时使用。

数据库健康

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

• 索引健康。查找未使用的索引、重复的索引以及臃肿的索引。臃肿的索引会导致数据库页面利用率低下。Postgres 自动清理会清理指向死元组的索引条目，并将这些条目标记为可重用。但是，它不会压缩索引页，最终导致索引页中可能只包含少量活跃的元组引用。
• 缓冲区缓存命中率。衡量从缓冲区缓存而非磁盘读取数据库的比例。必须调查较低的缓冲区缓存命中率，因为它通常不是成本最优的，并且会导致应用程序性能下降。
• 连接健康。检查数据库连接数并报告其使用情况。最大的风险是连接耗尽，但大量空闲或阻塞的连接也可能表明存在问题。
• 真空健康。真空之所以重要，原因有很多。其中一个关键点是防止事务 ID 回绕，这可能导致数据库停止接受写入操作。Postgres 多版本并发控制 (MVCC) 机制要求每个事务都有一个唯一的事务 ID。但是，由于 Postgres 使用 32 位有符号整数作为事务 ID，因此它需要在最多 20 亿个事务之后重用事务 ID。为此，它会“冻结”历史事务的事务 ID，将它们全部设置为表示遥远过去的特殊值。当记录首次写入磁盘时，它们会被写入一系列事务 ID 的可见性。在重新使用这些事务 ID 之前，Postgres 必须更新所有磁盘记录，将其“冻结”以删除对要重用的事务 ID 的引用。此检查会查找需要真空处理的表，以防止事务 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 通常能够生成 SQL 以直接从 Postgres 检索此信息时，为什么还要提供模式信息工具？

我们使用 Claude 的经验表明，调用 Claude 的 LLM 非常擅长通过查询Postgres 系统目录和信息模式（ANSI 标准化的数据库元数据视图）来生成 SQL 语句，从而探索 Postgres 模式。然而，我们不确定其他 LLM 是否也能如此可靠且高效地完成这项工作。

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

参考 PostgreSQL MCP 服务器使用资源（而非工具）来公开架构信息。资源导航类似于文件系统导航，因此这种方法在很多方面都很自然。然而，在 MCP 客户端生态系统中，资源支持不如工具支持广泛（参见示例客户端）。此外，虽然 MCP 标准规定资源可以由 AI 代理或最终用户访问，但某些客户端仅支持人工导航资源树。

受保护的 SQL 执行

人工智能加剧了长期以来保护数据库免受各种威胁（从简单的错误到恶意行为者的复杂攻击）的挑战。无论威胁是意外的还是恶意的，都适用类似的安全框架，其目标分为三类：机密性、完整性和可用性。便捷性和安全性之间常见的矛盾也显而易见。

Postgres MCP Pro 的受保护 SQL 执行模式注重完整性。在 MCP 环境中，我们最担心的是 LLM 生成的 SQL 会造成损害——例如，意外的数据修改或删除，或其他可能规避组织变更管理流程的更改。

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

Postgres MCP 提供只读事务模式，可防止数据和架构被修改。与参考 PostgreSQL MCP 服务器一样，我们使用只读事务来提供受保护的 SQL 执行。

为了使该机制健壮，我们需要确保 SQL 不会以某种方式规避只读事务模式，比如通过发出COMMIT或ROLLBACK语句然后开始新的事务。

例如，LLM 可以通过发出ROLLBACK语句并开始新事务来规避只读事务模式。例如：

为了防止此类情况发生，我们会在执行 SQL 语句之前使用pglast库对其进行解析。我们会拒绝任何包含commit或rollback语句的 SQL 语句。值得一提的是，主流的 Postgres 存储过程语言（包括 PL/pgSQL 和 PL/Python）都不允许使用COMMIT或ROLLBACK语句。如果您的数据库启用了不安全的存储过程语言，那么我们的只读保护机制可能会被绕过。

目前，Postgres MCP Pro 为数据库提供了两种级别的保护，分别处于便利性/安全性的两个极端。

• “无限制”模式提供了最大的灵活性。它适用于速度和灵活性至关重要，且无需保护宝贵或敏感数据的开发环境。
• “受限”在灵活性和安全性之间取得了平衡。它适用于数据库暴露给不受信任的用户的生产环境，以及保护有价值或敏感数据非常重要的环境。

不受限制模式与Cursor 自动运行模式的方法一致，在该模式下，AI 代理在有限的人工监督或批准下运行。我们期望自动运行模式部署在以下开发环境中：错误后果较轻，数据库不包含有价值或敏感的数据，并且可以在需要时重新创建或从备份中恢复。

我们设计受限模式时秉持着保守的原则，宁可牺牲安全性，即使它可能带来不便。受限模式仅限于只读操作，并且我们限制查询执行时间，以防止长时间运行的查询影响系统性能。未来我们可能会添加其他措施，以确保受限模式在生产数据库中能够安全使用。

Postgres MCP Pro 开发

以下说明适用于想要使用 Postgres MCP Pro 的开发人员，或喜欢从源代码安装 Postgres MCP Pro 的用户。

本地开发设置

1. 安装 uv ：
   curl -sSL https://astral.sh/uv/install.sh | sh
2. 克隆存储库：
   git clone https://github.com/crystaldba/postgres-mcp.git cd postgres-mcp
3. 安装依赖项：
   uv pip install -e . uv sync
4. 运行服务器：
   uv run postgres-mcp "postgres://user:password@localhost:5432/dbname"