postgres

PostgreSQL

一个提供 PostgreSQL 数据库只读访问权限的模型上下文协议服务。此服务支持大模型检查数据库架构并执行只读查询。

组件

工具

• pg-query

  • 对已连接的数据库执行只读 SQL 查询
  • 输入：sql（字符串）：要执行的 SQL 查询
  • 所有查询都在 READ ONLY 事务中执行

• pg-stats

  • 获取指定表的统计信息
  • 输入：name（字符串）：要获取统计信息的表名

• pg-explain

  • 解释给定 SQL 查询的执行计划
  • 输入：sql（字符串）：要解释的 SQL 查询

• pg-connect

  • 连接到 PostgreSQL 数据库
  • 输入：
    • connectionString（字符串）：不含凭据的 PostgreSQL 连接字符串（例如 postgresql://host:port/dbname 或 host:port/dbname）
    • user（字符串）：PostgreSQL 用户名
    • password（字符串）：PostgreSQL 密码

示例： pg-connect host.docker.internal:5432/postgres postgres pg_2025

• pg-awr
  • 生成类似 Oracle AWR 的 PostgreSQL 性能报告。包括数据库统计信息、热门查询（需要 pg_stat_statements 扩展）、表和索引统计信息、连接信息以及优化建议。

资源

此服务提供数据库中每个表的架构信息：

• 表架构（postgres://<dbname>/<table>/schema）
  • 每个表的 JSON 架构信息
  • 包含列名和数据类型
  • 自动从数据库元数据中发现

变更日志

变更历史请参阅变更日志。

配置

PostgreSQL 服务使用环境变量或 pg-connect 工具来安全管理凭据：

• PG_USER：PostgreSQL 用户名（使用 pg-connect 时可选）
• PG_PASSWORD：PostgreSQL 密码（使用 pg-connect 时可选）

连接字符串

连接字符串只应包含主机、端口和数据库信息（不包含内嵌凭据）。可选将其作为命令行参数提供。如果启动时未提供，则必须先使用 pg-connect 工具建立连接，才能使用其他功能。

支持的连接字符串格式：

• postgresql://host:port/dbname
• host:port/dbname

要启用加密（SSL），请在连接字符串后追加 ?sslmode=require，或将 PG_SSL 环境变量设为 true。

与 Claude Desktop 配合使用

要将此服务与 Claude Desktop 应用配合使用，请将以下配置添加到 claude_desktop_config.json 的 "mcpServers" 部分：

Docker

• 在 macOS 上运行 Docker 时，如果 PostgreSQL 服务运行在主机网络上（例如 localhost），请使用 host.docker.internal
• 凭据通过环境变量 PG_USER 和 PG_PASSWORD 传递

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", 
        "-i", 
        "--rm",
        "-e", "PG_USER=myuser",
        "-e", "PG_PASSWORD=mypassword",
        "mochoa/mcp-postgres"
      ]
    }
  }
}

注意：如果希望在启动时自动连接，仍可将连接字符串作为最后一个参数提供："args": [..., "mochoa/mcp-postgres", "postgresql://host.docker.internal:5432/mydb"]。

NPX

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@marcelo-ochoa/server-postgres",
        "postgresql://localhost:5432/mydb"
      ],
      "env": {
        "PG_USER": "myuser",
        "PG_PASSWORD": "mypassword"
      }
    }
  }
}

将 /mydb 替换为你的数据库名称。

注意：请将以下占位符替换为实际值：

• 将 myuser 和 mypassword 替换为你的 PostgreSQL 凭据
• 将 localhost:5432 替换为你的 PostgreSQL 服务主机和端口
• 将 mydb 替换为你的数据库名称

在 VS Code 中使用

如需快速安装，请使用下方的一个一键安装按钮……

如需手动安装，请将以下 JSON 代码块添加到 VS Code 的 User Settings (JSON) 文件中。按下 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 即可完成此操作。

也可以将其添加到工作区中名为 .vscode/mcp.json 的文件中。这样便可与他人共享此配置。

注意，.vscode/mcp.json 文件中不需要 mcp 键。

Docker

注意：使用 Docker 连接主机上的 PostgreSQL 服务时，请在连接 URL 中使用 host.docker.internal，而非 localhost。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pg_user",
        "description": "PostgreSQL username"
      },
      {
        "type": "promptString",
        "id": "pg_password",
        "description": "PostgreSQL password",
        "password": true
      }
    ],
    "servers": {
      "postgres": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e", "PG_USER=${input:pg_user}",
          "-e", "PG_PASSWORD=${input:pg_password}",
          "mochoa/mcp-postgres",
          "postgresql://localhost:5432/mydb"
        ]
      }
    }
  }
}

注意：如果希望启动时连接，可以为 pg_url 添加一个输入，并将其附加到 args 中。

NPX

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pg_user",
        "description": "PostgreSQL username"
      },
      {
        "type": "promptString",
        "id": "pg_password",
        "description": "PostgreSQL password",
        "password": true
      }
    ],
    "servers": {
      "postgres": {
        "command": "npx",
        "args": [
          "-y",
          "@marcelo-ochoa/server-postgres",
          "postgresql://localhost:5432/mydb"
        ],
        "env": {
          "PG_USER": "${input:pg_user}",
          "PG_PASSWORD": "${input:pg_password}"
        }
      }
    }
  }
}

PostgreSQL AWR 实战

请参阅 PostgreSQL AWR 实战，了解 pg-awr 工具为生产环境中的 Moodle 数据库生成的性能报告示例，其中指出了关键性能问题和优化机会。

演示

请参阅演示，查看使用 Claude Desktop、Docker AI、Gemini CLI 和 Antigravity Code Editor 的示例。

构建

Docker：

docker build -t mochoa/mcp-postgres -f src/postgres/Dockerfile .

来源

与往常一样，此扩展的代码位于 GitHub。欢迎提出修改建议并参与贡献。请注意，我是 React 和 TypeScript 初学者，因此也欢迎大家为改进此界面作出贡献。

📜 许可证

本项目的新贡献采用 Apache License 2.0 许可，现有代码采用 MIT 许可。详情请参阅 LICENSE 文件。