PostgreSQL MCP 服务器

一个基于 Model Context Protocol (MCP) 的 PostgreSQL 数据库查询服务器，让 AI 助手能够安全地访问和查询您的数据库。

📋 目录

• 功能特性
• 快速开始
• 项目结构
• 配置说明
• 使用方法
• MCP 客户端配置
• 安全建议
• 故障排除

✨ 功能特性

• ✅ SQL 查询 - 执行 SELECT 查询语句
• ✅ 数据修改 - 执行 INSERT、UPDATE、DELETE 操作
• ✅ 表管理 - 列出数据库中的所有表
• ✅ 表结构查询 - 查看表的列信息、数据类型等
• ✅ 表统计信息 - 获取表的行数、大小等详细信息
• ✅ 参数化查询 - 支持参数化查询，防止 SQL 注入
• ✅ 自动连接管理 - 自动管理数据库连接池

🚀 快速开始

前置要求

• Python 3.10 或更高版本
• PostgreSQL 数据库（本地或远程）
• pip 包管理器

安装步骤

1. 克隆或下载项目

git clone <repository_url>
cd ai-mcp

2. 创建虚拟环境

python -m venv venv

3. 激活虚拟环境

Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Windows (CMD):

venv\Scripts\activate.bat

Linux/Mac:

source venv/bin/activate

4. 安装依赖

pip install -r requirements.txt

5. 配置数据库连接

复制环境变量模板并编辑：

Windows:

copy env_template.txt .env

Linux/Mac:

cp env_template.txt .env

编辑 .env 文件，填入您的数据库连接信息：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=your_password_here

6. 测试运行（可选）

python postgres_mcp_server.py

如果看到 "数据库连接成功" 的日志，说明配置正确。

📁 项目结构

ai-mcp/
├── postgres_mcp_server.py  # MCP 服务器主程序
├── requirements.txt         # Python 依赖包列表
├── env_template.txt         # 环境变量配置模板
├── README.md               # 项目说明文档（本文件）
├── .env                    # 数据库连接配置（需自行创建）
└── venv/                   # Python 虚拟环境目录

⚙️ 配置说明

环境变量

在 .env 文件中配置以下变量：

变量名	说明	默认值	示例
DB_HOST	数据库主机地址	localhost	192.168.1.100
DB_PORT	数据库端口	5432	5432
DB_NAME	数据库名称	postgres	my_database
DB_USER	数据库用户名	postgres	db_user
DB_PASSWORD	数据库密码	(空)	your_secure_password

依赖包

项目依赖以下 Python 包（已在 requirements.txt 中定义）：

• mcp>=1.0.0 - Model Context Protocol SDK
• psycopg2-binary>=2.9.0 - PostgreSQL 数据库驱动
• python-dotenv>=1.0.0 - 环境变量管理

📖 使用方法

直接运行（测试用）

python postgres_mcp_server.py

作为 MCP 服务器运行

MCP 服务器设计为通过 stdio 协议运行，需要配合 MCP 客户端使用（如 Claude Desktop、Cursor 等）。

可用工具（Tools）

服务器提供以下 5 个工具：

1. query - 执行查询

执行 SQL 查询语句并返回结果。

参数：

• sql (string, 必需) - SQL 查询语句
• params (array, 可选) - 查询参数列表

示例：

{
  "sql": "SELECT * FROM users WHERE age > %s LIMIT 10",
  "params": [18]
}

2. execute - 执行修改

执行 INSERT、UPDATE、DELETE 等数据修改操作。

参数：

• sql (string, 必需) - SQL 修改语句
• params (array, 可选) - 查询参数列表

示例：

{
  "sql": "INSERT INTO users (name, email) VALUES (%s, %s)",
  "params": ["张三", "zhangsan@example.com"]
}

3. list_tables - 列出所有表

列出指定模式中的所有表和视图。

参数：

• schema (string, 可选) - 模式名称，默认为 "public"

示例：

{
  "schema": "public"
}

4. describe_table - 查看表结构

获取表的列信息（列名、数据类型、是否可空、默认值等）。

参数：

• table_name (string, 必需) - 表名
• schema (string, 可选) - 模式名称，默认为 "public"

示例：

{
  "table_name": "users",
  "schema": "public"
}

5. get_table_info - 获取表详细信息

获取表的统计信息（行数、表大小、索引大小等）。

参数：

• table_name (string, 必需) - 表名
• schema (string, 可选) - 模式名称，默认为 "public"

示例：

{
  "table_name": "users",
  "schema": "public"
}

🔌 MCP 客户端配置

Claude Desktop

配置文件位置

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

配置示例

{
  "mcpServers": {
    "postgres": {
      "command": "python",
      "args": ["D:\\desk\\code\\python\\ai-mcp\\postgres_mcp_server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

注意：

• Windows 路径需要使用双反斜杠 \\ 或单正斜杠 /
• 确保 Python 在系统 PATH 中，或使用完整路径（如 C:\\Python312\\python.exe）

Cursor

配置文件位置

• Windows: %USERPROFILE%\.cursor\mcp.json
• Mac/Linux: ~/.cursor/mcp.json

配置示例

{
  "mcpServers": {
    "postgres": {
      "command": "python",
      "args": ["D:\\desk\\code\\python\\ai-mcp\\postgres_mcp_server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "your_database",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

配置后的使用

配置完成后，重启 Claude Desktop 或 Cursor，您就可以在对话中直接使用自然语言查询数据库了：

示例对话：

用户：列出数据库中的所有表
AI：[调用 list_tables 工具]

用户：查询 china_highway_wgs84 表中有多少条数据
AI：[调用 query 工具执行 SELECT COUNT(*)]

用户：显示 users 表的结构
AI：[调用 describe_table 工具]

🔒 安全建议

1. 数据库权限控制

强烈建议为 MCP 服务器创建一个专用的数据库用户，并只授予必要的权限：

-- 创建只读用户（推荐用于查询）
CREATE USER mcp_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;

-- 如果需要修改权限（谨慎授予）
GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO mcp_readonly;

2. 环境变量安全

• ❌ 不要将 .env 文件提交到版本控制系统
• ✅ 将 .env 添加到 .gitignore
• ✅ 使用强密码
• ✅ 定期更换数据库密码

3. 网络安全

• 如果数据库在远程服务器，使用 SSL/TLS 加密连接
• 限制数据库的网络访问（使用防火墙规则）
• 考虑使用 VPN 或 SSH 隧道

4. 查询限制

考虑在数据库层面设置：

• 查询超时时间
• 结果集大小限制
• 连接数限制

🐛 故障排除

问题 1: 无法连接到数据库

错误信息： could not connect to server 或 connection refused

解决方案：

1. 确认 PostgreSQL 服务正在运行

   # Windows
   services.msc  # 查找 PostgreSQL 服务
   
   # Linux
   sudo systemctl status postgresql
   

2. 检查 .env 文件中的连接信息是否正确

3. 确认数据库允许来自客户端的连接（检查 pg_hba.conf）

4. 检查防火墙是否阻止了连接

问题 2: 认证失败

错误信息： password authentication failed

解决方案：

1. 确认用户名和密码正确
2. 检查用户是否有访问该数据库的权限
3. 查看 PostgreSQL 的 pg_hba.conf 配置

问题 3: 模块导入错误

错误信息： ModuleNotFoundError: No module named 'xxx'

解决方案：

1. 确认虚拟环境已激活
2. 重新安装依赖：

   pip install -r requirements.txt
   

问题 4: MCP 客户端无法找到服务器

解决方案：

1. 确认配置文件路径正确
2. 检查 JSON 格式是否正确（使用 JSON 验证器）
3. 确认 Python 可执行文件路径正确
4. 查看客户端的日志文件（通常在配置文件同目录）
5. 重启 MCP 客户端应用

问题 5: 中文显示乱码

解决方案： 确保数据库使用 UTF-8 编码：

-- 查看数据库编码
SHOW SERVER_ENCODING;

-- 创建新数据库时指定编码
CREATE DATABASE mydb WITH ENCODING 'UTF8';

📝 开发说明

日志配置

服务器使用 Python 的 logging 模块记录日志。修改日志级别：

# 在 postgres_mcp_server.py 中修改
logging.basicConfig(
    level=logging.DEBUG,  # 改为 DEBUG 查看详细日志
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

扩展功能

如需添加新的工具，参考现有工具的实现：

1. 在 list_tools() 中添加工具定义
2. 在 call_tool() 中添加工具调用
3. 实现具体的处理函数

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📚 相关资源

• Model Context Protocol 官方文档
• PostgreSQL 官方文档
• psycopg2 文档

❓ 常见问题

Q: 这个服务器安全吗？
A: 服务器本身不暴露网络端口，只通过 stdio 与 MCP 客户端通信。但请务必遵循安全建议，使用专用数据库用户并限制权限。

Q: 可以连接多个数据库吗？
A: 当前版本只支持连接一个数据库。如需连接多个数据库，可以配置多个 MCP 服务器实例。

Q: 支持其他数据库吗（如 MySQL、SQLite）？
A: 当前只支持 PostgreSQL。如需支持其他数据库，需要修改代码并使用相应的数据库驱动。

Q: 查询结果有大小限制吗？
A: 没有硬性限制，但返回大量数据可能会影响性能。建议在查询中使用 LIMIT 子句限制结果数量。

---

项目版本： 1.0.0
最后更新： 2025年10月