PostgreSQL MCP Server (Model Context Protocol)

PostgreSQL MCP 服务

一个由 FastMCP 驱动的 Model Context Protocol 服务，可让 AI 助手（Claude、Cursor 等）全面、结构化地访问 PostgreSQL 数据库，用户无需了解 SQL。

---

概述

此服务通过 stdio 传输，将 PostgreSQL 数据库作为一组 MCP 资源（只读视图）和 MCP 工具（读写操作）提供。任何兼容 MCP 的 AI 客户端都可以连接、检查架构，并使用自然语言执行数据操作。

Claude / Cursor / any MCP client
        │  stdio (MCP protocol)
        ▼
 postgres_mcp_server.py   (FastMCP layer — resources & tools)
        │  async
        ▼
 postgres_manager.py      (asyncpg connection pool)
        │
        ▼
  PostgreSQL Database

---

功能

类别	功能
架构	列出所有表，检查列定义
读取	支持筛选、排序和行数限制的查询
写入	插入、更新、删除行
DDL	创建和删除表
原始 SQL	执行任意查询
安全性	全程使用参数化查询（防止 SQL 注入）
日志记录	每次工具或资源调用都会输出结构化日志

---

MCP 资源

资源是只读、可通过 URI 访问的数据流，AI 客户端可以订阅这些数据流。

URI	描述
postgres://tables	数据库中所有表的 JSON 列表
postgres://schema/{table_name}	表的列名、类型和约束
postgres://data/{table_name}	表的前 100 行（安全预览）

---

MCP 工具

工具是 AI 可以代表你调用的操作。

execute_query

执行任意原始 SQL 语句，并以 JSON 格式返回结果。

query: str  — the SQL to run

create_table

使用自定义列定义创建新表。

table_name: str
columns:    [{"name": "id", "type": "SERIAL PRIMARY KEY"}, ...]

drop_table

永久删除表。

table_name: str

insert_data

向表中插入单行数据。

table_name: str
data:       {"column": value, ...}

update_data

更新符合条件的行。

table_name:       str
data:             {"column": new_value, ...}
condition:        "id = %s"
condition_params: [42]

delete_data

删除符合条件的行。

table_name:       str
condition:        "status = %s"
condition_params: ["inactive"]

select_data

查询表，支持可选的筛选、排序和分页。

table_name:       str
columns:          ["id", "name"]          (optional, default: *)
condition:        "age > %s"              (optional)
condition_params: [18]                    (optional)
order_by:         "created_at DESC"       (optional)
limit:            100                     (optional, default: 100)

---

前置条件

• Python 3.8+
• PostgreSQL 服务（本地或远程）
• uv 包管理器（推荐）——或 pip
• 兼容 MCP 的 AI 客户端（Claude Desktop、Cursor 等）

---

安装

# 1. Clone the repository
git clone https://github.com/VivekMalipatel/Postgres_MCP_Server.git
cd Postgres_MCP_Server

# 2. Create and activate a virtual environment
python -m venv .mcp
source .mcp/bin/activate        # macOS / Linux
# .mcp\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

---

配置

在项目根目录中创建 .env 文件：

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password

---

连接到 Claude Desktop

将以下配置块添加到 Claude Desktop 的 MCP 配置文件中
（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "PostgreSQL MCP": {
      "command": "/absolute/path/to/.mcp/bin/uv",
      "args": [
        "run",
        "--with", "mcp[cli]",
        "--with", "asyncpg",
        "--with", "httpx",
        "--with", "python-dotenv",
        "--with", "psycopg2-binary",
        "mcp",
        "run",
        "/absolute/path/to/postgres_mcp_server.py"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

将所有 /absolute/path/to/ 替换为计算机上的实际路径。
如果使用 .env 文件，则可以省略 env 配置块。

---

手动运行（stdio）

python postgres_mcp_server.py

服务启动后会等待从 stdin 接收 MCP 协议消息。正常使用时，AI 客户端会通过上述配置自动启动此服务。

---

依赖项

软件包	用途
mcp[cli]	MCP 协议和 FastMCP 框架
asyncpg	高性能异步 PostgreSQL 驱动程序
psycopg2-binary	同步 PostgreSQL 驱动程序（备用）
python-dotenv	加载 .env 文件
httpx	异步 HTTP 客户端（工具可用）
uvicorn	ASGI 服务（用于未来的 HTTP 传输）
uv	快速 Python 软件包运行器

---

项目结构

Postgres_MCP_Server/
├── postgres_mcp_server.py   # FastMCP server — resources, tools, lifespan
├── postgres_manager.py      # Async DB manager (connection pool, CRUD)
├── requirements.txt
└── .env                     # (create this — not committed)

---

许可证

MIT — 可免费使用、修改和分发。