Simple PostgreSQL MCP Server

简易 PostgreSQL MCP 服务

这是一个模板项目，适合希望构建自己的 MCP 服务的人。我设计它时力求简单易懂、易于改造——代码直观，并附有 MCP 文档，让你能快速上手。

什么是 MCP？

简而言之——这是一种为 AI 编写插件的方式

模型上下文协议（Model Context Protocol，MCP）是大模型与外部工具和数据交互的标准方式。简单来说：

• 工具允许大模型执行命令（例如运行数据库查询）
• 资源是可附加到对话中的数据（例如将文件附加到提示词）
• 提示词是用于生成一致的大模型指令的模板

功能

此 PostgreSQL MCP 服务实现了：

1. 工具

   • execute_query - 对数据库运行 SQL 查询
   • test_connection - 验证数据库连接是否正常

2. 资源

   • db://tables - 架构中的所有表的列表
   • db://tables/{table_name} - 特定表的架构信息
   • db://schema - 数据库中所有表的完整架构信息

3. 提示词

   • 查询生成模板
   • 分析查询构建器
   • 基于此仓库中的模板

前置条件

• Python 3.8+
• uv - 现代 Python 包管理器和安装程序
• npx（随 Node.js 一同安装）
• 可连接的 PostgreSQL 数据库

快速设置

1. 创建虚拟环境并安装依赖项：

   # Create a virtual environment with uv
   uv venv
   
   # Activate the virtual environment
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -r requirements.txt
   

2. 使用 MCP Inspector 运行服务：

   # Replace with YOUR actual database credentials
   npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public
   

   注意：如果这是你首次运行 npx，系统会提示你批准安装。输入 'y' 继续。

   运行此命令后，MCP Inspector 界面会在浏览器中打开。你应该会看到类似这样的消息：

   MCP Inspector is up and running at http://localhost:5173
   

   如果浏览器没有自动打开，请将 URL 复制并粘贴到浏览器中。你应该会看到类似这样的界面：

3. 使用 Inspector：

   • 点击界面中的 "Connect" 按钮（除非左下角的控制台中显示错误消息）
   • 浏览 "Tools"、"Resources" 和 "Prompts" 标签页，查看可用功能
   • 尝试点击列出的命令，或输入资源名称以检索资源和提示词
   • 该界面允许你测试查询，并查看 MCP 服务如何响应

4. 查看官方文档

   官方服务开发者指南：https://modelcontextprotocol.io/quickstart/server

   关于 Inspector 的更多信息：https://modelcontextprotocol.io/docs/tools/inspector

将 AI 工具连接到服务

你可以创建 MCP 配置文件，为 AI 助手配置 MCP 服务：

{
   "mcpServers": {
      "postgres": {
         "command": "/path/to/uv",
         "args": [
            "--directory",
            "/path/to/simple-psql-mcp",
            "run",
            "postgres"
         ],
         "env": {
            "DSN": "postgresql://username:password@localhost:5432/my-db",
            "SCHEMA": "public"
         }
      }
   }
}

或者，你也可以使用附带的脚本生成此配置文件：

# Make the script executable
chmod +x generate_mcp_config.sh

# Run the configuration generator
./generate_mcp_config.sh

出现提示时，输入你的 PostgreSQL DSN 和架构名称。

如何使用

现在，你可以用自然语言向大模型询问有关数据的问题：

• “我的数据库中有哪些表？”
• “按创建日期列出排名前 5 的用户”
• “按州统计地址数量”

Claude Desktop 原生支持 MCP，开箱即用，支持所有功能（工具、资源和提示词），适合进行测试。

示例数据库（可选）

如果你还没有准备好数据库，或遇到连接问题，可以使用附带的示例数据库：

# Make the script executable
chmod +x example-db/create-db.sh

# Run the database setup script
./example-db/create-db.sh

此脚本会创建一个 Docker 容器，其中包含一个 PostgreSQL 数据库，并预先填充了示例用户表和地址表。运行后，你可以使用以下信息连接：

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

后续步骤

要使用你自己的 MCP 服务扩展此项目：

1. 在 /src 下创建一个新目录（例如 /src/my-new-mcp）
2. 参考 PostgreSQL 示例实现你的 MCP 服务
3. 将新的 MCP 添加到 pyproject.toml：

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

然后，你可以通过以下命令运行新的 MCP：

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

文档

• 附带 MCP 文档，便于 LLM 开发
• 基于此处的方法：https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

安全性

这是一个实验性项目，旨在帮助开发者创建自己的 MCP 服务。我只做了最低限度的工作，确保你尝试使用时它不会立即崩溃，但请务必谨慎——使用此工具很容易执行 SQL 注入。服务会检查查询是否以 SELECT 开头，但除此之外无法保证任何安全性。简而言之——除非你是创始人且没有付费客户，否则不要在生产环境中运行。

许可证

MIT