简易PostgreSQL MCP服务器

这是一个为希望构建自己MCP服务器的开发者提供的模板项目。我设计它时力求简单易懂、便于修改——代码结构清晰，并附带MCP文档，帮助你快速上手。

什么是MCP？

简而言之——它是为AI编写插件的方式

模型上下文协议（MCP）是一种标准接口，允许大型语言模型（LLM）与外部工具和数据进行交互。核心概念包括：

• 工具：让LLM能够执行命令（如运行数据库查询）
• 资源：可附加到对话中的数据（如向提示附加文件）
• 提示模板：生成一致LLM指令的模板

功能特性

本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. 创建虚拟环境并安装依赖：

   # 使用uv创建虚拟环境
   uv venv
   
   # 激活虚拟环境
   source .venv/bin/activate  # Windows用户使用：.venv\Scripts\activate
   
   # 安装依赖
   uv pip install -r requirements.txt
   

2. 使用MCP检查器运行服务器：

   # 替换为你的实际数据库凭据
   npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://用户名:密码@主机名:端口/数据库名 -e SCHEMA=public
   

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

   执行后，你会在浏览器中看到MCP检查器界面，应该会显示类似消息：

   MCP检查器已在 http://localhost:5173 启动
   

   如果浏览器未自动打开，请将URL复制到浏览器中。你应该会看到如下界面：
   

3. 使用检查器：

   • 点击界面中的"连接"按钮（除非左下角控制台显示错误消息）
   • 浏览"工具"、"资源"和"提示"标签页查看可用功能
   • 尝试点击列出的命令或输入资源名称来获取资源和提示
   • 该界面允许你测试查询并查看MCP服务器的响应

4. 查看官方文档

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

   检查器更多信息：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://用户名:密码@localhost:5432/我的数据库",
            "SCHEMA": "public"
         }
      }
   }
}

或者，你可以使用包含的脚本生成此配置文件：

# 使脚本可执行
chmod +x generate_mcp_config.sh

# 运行配置生成器
./generate_mcp_config.sh

按提示输入你的PostgreSQL DSN和模式名称。

使用方法

现在你可以用自然语言向LLM询问关于你的数据的问题：

• "我的数据库中有哪些表？"
• "按创建日期显示前5名用户"
• "按州统计地址数量"

测试时，Claude Desktop原生支持MCP，并且开箱即用所有功能（工具、资源和提示）。

示例数据库（可选）

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

# 使脚本可执行
chmod +x example-db/create-db.sh

# 运行数据库设置脚本
./example-db/create-db.sh

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

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

文档

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

安全性

这是一个实验性项目，旨在帮助开发者创建自己的MCP服务器。我只做了最基本的工作确保它能立即运行，但请注意——使用这个工具非常容易发生SQL注入。服务器会检查查询是否以SELECT开头，但除此之外不做任何保证。简而言之——除非你是创始人且没有付费客户，否则不要在生产环境中运行。

许可证

MIT