PostgreSQL MCP Server

PostgreSQL MCP 服务

用于探索和查询 PostgreSQL 数据库的模型上下文协议（MCP）服务实现。

目录

• 概述
• 功能
• 要求
• 安装
• 用法
  • 基本用法
  • 与 Claude Desktop 搭配使用
  • 配置文件位置
• 可用工具
  • execute_query
  • list_tables
  • get_table_schema
  • filter_instances
  • get_database_stats
• 安全注意事项
• Claude 中的交互示例
• 故障排除
• 联系方式

概述

本项目提供了一个模型上下文协议（MCP）服务，可连接 PostgreSQL 数据库，并将各种数据发现和查询功能作为 MCP 工具提供。这些工具可通过标准化接口帮助你探索数据库结构、查询数据并获取数据库统计信息。

功能

• 使用标准连接字符串连接任意 PostgreSQL 数据库
• 执行自定义 SELECT 查询，并以结构化格式返回结果
• 列出已连接数据库中的所有表
• 获取任意表的详细架构信息
• 使用简单的相等条件筛选数据库记录
• 获取数据库统计信息，包括大小、表数量和最大的表

要求

• Python 3.7+
• 所需的 Python 包（列于 requirements.txt 中）：
  • mcp
  • pg8000
  • sqlalchemy

安装

1. 克隆此仓库或下载源代码
2. 创建虚拟环境（推荐）
3. 安装所需的软件包：

pip install -r requirements.txt

用法

基本用法

提供 PostgreSQL 连接字符串以运行服务：

python server.py postgresql://username:password@hostname:port/database

与 Claude Desktop 搭配使用

若要与 Claude Desktop 集成，请将以下配置添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "postgres": {
      "command": "python",
      "args": [
        "/ABOSLUTE/PATH/TO/postgres-mcp-server/server.py",
        "postgresql://user:password@host:port/database"
      ]
    }
  }
}

添加或修改上述配置文件后，请务必强制退出并重新启动 Claude Desktop。

配置文件位置

Claude Desktop 配置文件通常位于：

• macOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

可用工具

此服务提供以下 MCP 工具：

execute_query

执行自定义 SELECT SQL 查询并返回结果。

list_tables

列出当前 PostgreSQL 数据库中的所有表。

get_table_schema

获取指定表的架构定义。

filter_instances

根据指定条件筛选数据库记录。

get_database_stats

获取有关 PostgreSQL 数据库的常规统计信息和元数据。

安全注意事项

• 此服务仅允许 SELECT 查询，以防止修改数据库
• 通过命令行提供连接凭据，不会存储这些凭据
• 在生产环境中，建议使用环境变量或安全的配置方式

Claude 中的交互示例

连接到 Claude Desktop 后，你可以提出以下问题：

• “数据库中有哪些表？”
• “显示 customers 表的架构”
• “orders 表中有多少条记录？”
• “数据库的总大小是多少？”

Claude 会使用相应的 MCP 工具查询你的 PostgreSQL 数据库来回答这些问题。

故障排查

• 如果连接失败，请确认 PostgreSQL 连接字符串是否正确

• 检查 PostgreSQL 服务是否允许来自客户端计算机的连接

• 找不到服务：确保配置文件中的路径正确且为绝对路径

  运行 where python，使用命令的绝对路径

  例如，"command": "python" 应写为 "command": "/Users/username/miniconda3/bin/python"

• 权限问题：确保 Claude Desktop 应用有权限执行此脚本

• 服务崩溃：检查服务日志中的错误，并确保已安装所有依赖项

联系方式

欢迎在此代码库中提交问题。

SSE 和 Streamable-HTTP postgres-mcp-server 正在开发中……