使用说明

项目简介

Postgres-MCP Server 是一个实现了 Model Context Protocol (MCP) 协议的后端服务器，专门为 PostgreSQL 数据库设计。它旨在作为 LLM（大型语言模型）应用的上下文服务，允许 LLM 通过标准化的 MCP 协议安全、可扩展地访问和操作 PostgreSQL 数据库的功能。

主要功能点

资源 (Resources):
- 笔记存储: 提供简单的笔记存储系统，允许 LLM 客户端访问和管理笔记资源。
- 数据库表结构: 允许 LLM 客户端获取数据库中表的结构信息。
- PostgreSQL 扩展: 允许 LLM 客户端查询已安装的 PostgreSQL 扩展信息。
Prompt 模板 (Prompts):
- 笔记总结 (summarize-notes): 允许 LLM 客户端请求服务器生成所有存储笔记的摘要，并可选择摘要风格（简要/详细）。
工具 (Tools):
- 添加笔记 (add-note): 允许 LLM 客户端向服务器添加新的笔记。
- 执行 SQL 查询 (query): 允许 LLM 客户端执行只读 SQL 查询并获取结果。
- 分析工作负载 (analyze-workload): 分析数据库的频繁执行查询，并推荐优化的索引。
- 分析指定查询 (analyze-queries): 分析用户提供的 SQL 查询列表，并推荐优化的索引。
- 数据库健康检查 (database-health): 分析数据库的健康状况，包括索引、连接、Vacuum、Sequence、Replication、Buffer 和 Constraint 等方面。
- 列出已安装扩展 (list-installed-extensions): 列出数据库中已安装的 PostgreSQL 扩展。
- 安装扩展 (install-extension): 在数据库中安装指定的 PostgreSQL 扩展。
- 报告慢查询 (top-slow-queries): 报告数据库中最慢的 SQL 查询。

安装步骤

本仓库的代码是 MCP 服务器的后端实现，需要部署后才能被 MCP 客户端（例如 Claude）连接和使用。

1. 克隆仓库

首先，您需要克隆 'postgres-mcp' 仓库到本地：

git clone https://github.com/crystaldba/postgres-mcp
cd postgres-mcp

2. 安装依赖

使用 'uv' 或 'pip' 安装项目依赖：

uv sync  # 推荐使用 uv
# 或
pip install -r requirements.txt

3. 构建 (可选)

如果您需要构建分发包，可以运行：

uv build
# 或
python -m build

这将在 'dist/' 目录下创建 wheel 和 source 文件。

4. 发布 (可选)

如果您希望将包发布到 PyPI，可以运行：

uv publish
# 或
python -m twine upload dist/*

服务器配置

要使 MCP 客户端（如 Claude Desktop）能够连接到 Postgres-MCP Server，您需要在客户端的配置文件中添加服务器配置信息。

对于 Claude Desktop 客户端，配置文件路径通常为：

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

打开 'claude_desktop_config.json' 文件，在 '"mcpServers"' 字段下添加 'postgres-mcp' 服务器的配置。

开发/未发布服务器配置示例：

"mcpServers": {
  "postgres-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "{{PATH TO CHECKOUT}}/postgres-mcp",  //  请替换为 postgres-mcp 仓库在您本地的检出路径
      "run",
      "postgres-mcp",
      "{{POSTGRESQL DATABASE URL}}" // 请替换为您的 PostgreSQL 数据库连接 URL，例如：postgresql://user:password@host:port/database
    ]
  }
}

配置参数说明：

'"postgres-mcp"': 服务器名称，在客户端配置中用于标识和引用该服务器。
'"command": "uv"': 启动服务器的命令。这里使用 'uv run'，假设您已安装 'uv' 包管理器。您也可以使用 'python' 或 'python3'，并指定 'server.py' 脚本路径。
'"args"': 传递给启动命令的参数列表。
- '"--directory"' 和 '"{{PATH TO CHECKOUT}}/postgres-mcp"': 指定服务器代码所在的目录。 请务必将 '{{PATH TO CHECKOUT}}/postgres-mcp' 替换为您本地 'postgres-mcp' 仓库的实际路径。
- '"run"' 和 '"postgres-mcp"': 使用 'uv run' 运行 'postgres-mcp' 包，启动服务器。
- '"{{POSTGRESQL DATABASE URL}}"': 请务必替换为您的 PostgreSQL 数据库连接 URL。 URL 格式通常为 'postgresql://用户名:密码@主机:端口/数据库名'。

发布服务器配置示例 (用于已发布到 PyPI 的版本):

"mcpServers": {
  "postgres-mcp": {
    "command": "uvx",
    "args": [
      "postgres-mcp", // 假设 postgres-mcp 包已安装到环境中
      "{{POSTGRESQL DATABASE URL}}" // 请替换为您的 PostgreSQL 数据库连接 URL
    ]
  }
}

注意:

您需要将 '{{PATH TO CHECKOUT}}/postgres-mcp' 和 '{{POSTGRESQL DATABASE URL}}' 替换为实际的值。
确保 PostgreSQL 数据库服务已启动并可访问。
配置文件修改后，可能需要重启 MCP 客户端才能生效。

基本使用方法

配置完成后，您的 MCP 客户端（如 Claude）应该能够连接到 Postgres-MCP Server。您可以通过客户端的界面或命令来调用服务器提供的资源和工具。

例如，在 Claude 中，您可以：

使用 '@postgres-mcp://resources' URI 读取 'list_resources' 资源，查看可用的数据库资源。
使用 '@postgres-mcp:query' 工具，输入 SQL 查询语句，让服务器执行并返回结果。
使用 '@postgres-mcp:analyze-workload' 工具，分析数据库工作负载并获取索引优化建议。

具体的工具和资源 URI 可以参考仓库 'README.md' 文件或通过 'list_resources' 资源动态发现。

关键词