使用说明

PostgreSQL MCP服务器

PostgreSQL数据库的通用、可重用的模型上下文协议（MCP）服务器。该服务器提供智能数据库工具，可用于任何兼容MCP的AI客户端，如Cursor、带有GitHub Copilot的VS Code、Claude Desktop或任何其他MCP客户端。

🚀 特性

通用和可重复使用：只需配置连接字符串，即可与任何PostgreSQL数据库配合使用
零外部依赖：不需要OpenAI、Gemini或其他LLM API密钥-使用AI客户端自己的智能
自然语言就绪：为AI客户端提供模式上下文，以将自然语言转换为SQL
综合工具：5个强大的MCP工具，用于数据库探索和查询
异步性能：使用asyncpg构建，用于高性能异步操作
类型安全：全类型提示和Pydantic模型，确保可靠性
有据可查的：清晰的文档字符串和结构化的JSON响应

🧠 运作原理

此MCP服务器为您的AI客户端提供数据库上下文（游标、VS代码等）。AI客户端使用此上下文来：

了解您的数据库 使用 get_database_schema_summary
生成SQL查询 根据您的自然语言请求
执行查询 使用 execute_query
返回格式化结果 回到你身边

您不需要单独的API密钥 -您已经使用的AI客户端（Cursor、Claude等）处理所有的自然语言处理！

📦 MCP工具

1. `get_tables`

使用全面的元数据获取数据库中的所有表：

表名和架构
表类型（基本表或视图）
列计数
主键列
表格大小

参数：

schema （可选）：按架构名称筛选
include_views （可选）：在结果中包含视图

2. `get_routines_and_functions`

检索所有存储过程和函数：

函数名称和模式
参数（参数列表）
返回类型
例程类型（函数、过程、聚合、窗口）
语言（plpgsql、sql等）
完整定义

参数：

schema （可选）：按架构筛选
function_name_pattern （可选）：用于过滤的SQL LIKE模式

3. `get_database_schema_summary`

最有用的工具 -全面了解您的数据库：

所有包含元数据的表
详细栏目信息
约束和关系
功能和程序
汇总统计

这提供了AI理解数据库结构和生成适当查询所需的所有上下文。

无需参数 -归还一切！

4. `get_table_schema`

获取特定表的详细架构信息：

列定义（名称、类型、可空、默认）
约束（主键、外键、唯一性、检查）
索引（名称、类型、列、唯一性）

参数：

table_name：表的名称
schema：架构名称（默认：“public”）

5. `execute_query`

执行具有安全功能的SQL查询：

SELECT查询的自动限制
阻止破坏性操作（DROP、DELETE、UPDATE）
返回结构化结果

6. `get_connection_status`

调试工具，用于检查服务器是否配置了默认连接（对故障排除很有用）。

参数：

query：要执行的SQL查询
limit：要返回的最大行数（默认值：1000）

🛠️ 安装

⚠️ 重要提示：Python版本要求

如果你有Python 3.14，请先切换到3.12：
poetry env use python3.12
这 asyncpg 和 pydantic-core 库还不支持Python 3.14。

先决条件

Python 3.10、3.11、3.12或3.13(不是3.14)
PostgreSQL数据库（本地或云端）
诗歌（用于依赖管理）

设置

克隆存储库：

git clone <your-repo-url>
cd pgsql-mcp-server

安装依赖项：

# If you have Python 3.14, use Python 3.12 instead
poetry env use python3.12  # or python3.11, python3.10

poetry install

配置环境：

cp env.example .env
# Edit .env with your database credentials

环境变量：

选项1-单个参数：

DB_USER_NAME=your_user
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database

选项2-连接字符串（推荐）：

POSTGRES_CONNECTION_STRING=postgresql://user:password@host:port/database

⚠️ 重要提示：连接字符串格式

连接字符串必须位于 PostgreSQL URL格式:

postgresql://username:password@host:port/database

对于带有SSL的Azure PostgreSQL：

POSTGRES_CONNECTION_STRING=postgresql://user:password@server.postgres.database.azure.com:5432/database?sslmode=require

密码中的特殊字符

如果您的密码包含特殊字符必须 URL对它们进行编码：

字符	编码	字符	编码
`#`	`%23`	`@`	`%40`
`%`	`%25`	`&`	`%26`
`+`	`%2B`	`/`	`%2F`
`?`	`%3F`	`=`	`%3D`
`:` （单位：pwd）	`%3A`	（空格）	`%20`

例子：

# Original password: qA5m#6fMk
# Encoded password:  qA5m%236fMk

POSTGRES_CONNECTION_STRING=postgresql://myuser:qA5m%236fMk@host:5432/mydb

5.测试您的连接

运行连接测试以验证一切正常：

poetry run python test_connection.py

预期产量：

Testing connection to: postgresql://user:****@host:5432/database

Connecting to database...
[OK] Connected successfully!

Database: your_database
Version: PostgreSQL 16.x on ...

Testing table listing...
[OK] Found 5 tables (showing first 5):
  - schema.table1
  - schema.table2
  ...

[SUCCESS] All connection tests passed!

就是这样！ 不需要API密钥-剩下的由您的AI客户端处理。

🎯 用法

运行服务器

服务器支持两种传输模式：

stdio模式（默认） -对于直接MCP客户端集成：

poetry run python mcp_server.py

HTTP模式 -对于独立服务器（建议用于开发）：

poetry run python mcp_server.py --http

HTTP服务器将在 http://localhost:8000 MCP端点位于 http://localhost:8000/sse.

🔌 客户端集成

光标IDE设置

您可以通过两种方式配置Cursor以连接到MCP服务器：

推荐方法：HTTP传输✅

为什么这最有效：

✅ 配置简单-无路径问题
✅ 易于调试-查看所有服务器日志
✅ 独立服务器-在不重新启动Cursor的情况下重新启动
✅ 在所有系统中可靠工作

设置：

编辑光标MCP配置 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

以HTTP模式启动服务器 （在单独的终端中）：

cd /path/to/pgsql-mcp-server
poetry run python mcp_server.py --http

您应该看到：

INFO:__main__:Starting PostgreSQL MCP Server...
INFO:__main__:Connection target: your-host:5432/your-database
INFO:__main__:Running in HTTP mode on http://localhost:8000
INFO:__main__:MCP endpoint: http://localhost:8000/sse

重新启动游标
保持服务器运行 -不要关闭终端。您可以实时查看所有日志。

替代方案：stdio传输（自动启动）

注：这种方法在某些系统上可能存在路径解析问题。如果遇到问题，请使用上面的HTTP方法。

编辑光标MCP配置 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "postgres": {
      "command": "poetry",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/absolute/path/to/pgsql-mcp-server",
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/pgsql-mcp-server 根据您的实际路径（例如。， /Users/username/Projects/pgsql-mcp-server/pgsql-mcp-server).

重新启动游标

测试集成：

打开Cursor的AI聊天并尝试：

“显示数据库中的所有表”
“用户表的架构是什么？”
“获取过去30天内注册的所有用户”
“按产品类别显示总销售额”

AI将自动：

呼叫 get_database_schema_summary 了解您的数据库
生成适当的SQL查询
使用执行它 execute_query
格式化并解释结果

VS代码与GitHub副本设置

启动MCP服务器 （在单独的终端中）：

cd /path/to/pgsql-mcp-server
poetry run python mcp_server.py --http

创建或编辑 .vscode/settings.json 在您的项目中：

{
  "mcp.servers": {
    "postgres": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

重新加载VS代码
使用副驾驶聊天 用自然语言查询数据库

保持服务器运行 在后台保持连接。

Claude桌面设置

启动MCP服务器 （在单独的终端中）：

cd /path/to/pgsql-mcp-server
poetry run python mcp_server.py --http

编辑Claude桌面配置：

在macOS上： ~/Library/Application Support/Claude/claude_desktop_config.json

在Windows上： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
    }
  }
}

重新启动克劳德桌面

保持服务器运行 在后台-克劳德将自动连接到它。

与LangGraph代理一起使用

您还可以通过编程方式使用此服务器：

启动MCP服务器:

poetry run python mcp_server.py --http

在Python代码中使用:

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

async def main():
    # Connect to the MCP server (HTTP transport)
    client = MultiServerMCPClient({
        "postgres": {
            "url": "http://localhost:8000/sse",
            "transport": "sse",
        },
    })
    
    # Get tools from the server
    tools = await client.get_tools()
    
    # Create an agent with the tools
    llm = ChatOpenAI(model="gpt-4")
    agent = create_react_agent(model=llm, tools=tools)
    
    # Use the agent
    result = await agent.ainvoke({
        "messages": [{
            "role": "user",
            "content": "Show me all users who registered in the last 30 days"
        }]
    })
    
    print(result["messages"][-1].content)

asyncio.run(main())

📋 查询示例

一旦与您的MCP客户端集成，您就可以用简单的英语提问：

数据库探索：

“数据库中有哪些表？”
“显示完整的数据库架构”
“用户表的结构是什么？”
“列出所有存储过程”

数据查询：

“显示过去7天内购买的所有客户”
“获得收入排名前10的产品及其类别名称”
“查找所有员工及其部门和经理信息”
“最近的订单有哪些客户详细信息？”
“按每个产品类别的状态统计订单”

复杂接头：

“向我显示用户的订单和订单项”
“通过总订单和总支出获得客户终身价值”
“查找从未订购过的产品”

AI将：

分析你的问题
使用获取数据库架构 get_database_schema_summary
如果需要，使用JOIN生成适当的SQL
使用执行 execute_query
为您格式化结果

🏗️ 项目结构

pgsql-mcp-server/
├── config.py                    # Configuration settings
├── mcp_server.py                # Main MCP server with all tools
├── db_connection.py             # PostgreSQL connection manager
├── pg_tools.py                  # Database tool implementations
├── env.example                  # Example environment configuration
├── pyproject.toml               # Poetry dependencies
├── poetry.lock                  # Locked dependencies
├── .gitignore                   # Git ignore rules
├── README.md                    # This file (comprehensive docs)
├── QUICKSTART.md                # Quick start guide (5 min setup)
├── PROJECT_SUMMARY.md           # Project overview
├── CHANGELOG.md                 # Version history & changes
├── CODE_OF_CONDUCT.md           # Community guidelines
├── LICENSE.md                   # MIT License
└── REVIEW.md                    # Code review & quality assessment

🔒 安全注意事项

默认情况下为只读：The execute_query 该工具阻止破坏性操作（DROP、DELETE、UPDATE）
查询限制：SELECT查询中添加了自动LIMIT子句（默认值：1000行）
连接池：使用asyncpg连接池实现稳定性
环境变量：将凭据保存在环境变量中，而不是代码中
无外部API：没有数据离开您的环境-一切都是本地的

🐛 故障排除

连接问题

问题：“初始化数据库池失败”或“int（）的文本无效”

解决方案:

检查连接字符串格式 -必须是： postgresql://user:password@host:port/database
- 没有。NET格式，带分号： Host=...;Database=...

URL编码密码中的特殊字符:

# Wrong: password with # character
POSTGRES_CONNECTION_STRING=postgresql://user:pass#word@host:5432/db

# Correct: # encoded as %23
POSTGRES_CONNECTION_STRING=postgresql://user:pass%23word@host:5432/db

测试连接:
```
poetry run python test_connection.py
```

手动验证凭据:

psql "postgresql://user:password@host:port/database"

适用于Azure PostgreSQL，添加 ?sslmode=require:

POSTGRES_CONNECTION_STRING=postgresql://user:password@server.postgres.database.azure.com:5432/db?sslmode=require

问题：“Python 3.14比PyO3支持的最大版本更新”

解决方案:

# Use Python 3.12 instead
poetry env use python3.12
poetry install

MCP客户端找不到工具

问题：客户表示“没有可用工具”

解决方案:

对于HTTP传输：

确保服务器正在运行： poetry run python mcp_server.py --http
检查mcp.json中的URL： http://localhost:8000/sse
验证服务器是否可访问：打开 http://localhost:8000/sse 浏览器中
检查服务器日志是否有错误

对于stdio传输：

验证 cwd mcp.json中的路径是绝对的（不是相对的）
检查mcp.json中的环境变量是否设置正确
查看Cursor的日志以查找服务器启动错误

两者：

重新启动MCP客户端（光标/VS代码）
测试连接： poetry run python test_connection.py

查询不起作用

问题：“执行查询时出错”

解决方案:

让AI显示生成的SQL
验证表/列名是否正确
检查您是否具有对表的读取权限
先尝试一个更简单的查询（例如，“显示所有表”）

💡 提示

从模式探索开始：在运行复杂查询之前，先问“数据库中有什么？”
具体说明：不要“显示用户”，尝试“显示所有用户的电子邮件和注册日期”
审核生成的SQL：让AI向您展示它生成的SQL
使用自然语言：你不需要知道SQL，只需描述你想要什么

🤝 贡献

欢迎投稿！拜托：

阅读我们的行为准则
分叉存储库
创建要素分支
进行更改
提交拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证.md 文件以获取详细信息。

🙏 致谢

内置：

FastMCP -MCP服务器框架
asyncpg -快速PostgreSQL驱动程序
派丹蒂克 -数据验证

通过AI客户端用自然语言查询PostgreSQL数据库！ 🚀

使用说明

PostgreSQL MCP服务器

🚀 特性

🧠 运作原理

📦 MCP工具

1. get_tables

2. get_routines_and_functions

3. get_database_schema_summary

4. get_table_schema

5. execute_query

6. get_connection_status

🛠️ 安装

⚠️ 重要提示：Python版本要求

先决条件

设置

⚠️ 重要提示：连接字符串格式

对于带有SSL的Azure PostgreSQL：

密码中的特殊字符

5.测试您的连接

🎯 用法

运行服务器

🔌 客户端集成

光标IDE设置

推荐方法：HTTP传输✅

替代方案：stdio传输（自动启动）

VS代码与GitHub副本设置

Claude桌面设置

与LangGraph代理一起使用

📋 查询示例

🏗️ 项目结构

🔒 安全注意事项

🐛 故障排除

连接问题

MCP客户端找不到工具

查询不起作用

💡 提示

🤝 贡献

📄 许可证

🙏 致谢

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

MySQL数据库管理工具

1. `get_tables`

2. `get_routines_and_functions`

3. `get_database_schema_summary`

4. `get_table_schema`

5. `execute_query`

6. `get_connection_status`