简单的PostgreSQL MCP服务器

这是一个模板项目，供那些想要构建自己的MCP服务器的人使用。我设计它是为了简单易懂且易于适应——代码非常直接，并附有MCP文档，以便您快速上手。

什么是MCP？

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

模型上下文协议（MCP）是一种标准方法，用于LLMs与外部工具和数据进行交互。简而言之：

• 工具允许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 Inspector运行服务器：

   # 替换为您实际的数据库凭据
   npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public
   

   注意：如果您第一次运行npx，系统会提示您批准安装。输入'y'继续。

   运行此命令后，您将在浏览器中看到MCP Inspector界面。您应该看到类似的消息：

   MCP Inspector正在http://localhost:5173运行
   

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

3. 使用Inspector：

   • 在界面上点击“连接”按钮（除非在左下角控制台中有错误消息）
   • 浏览“工具”、“资源”和“提示”标签以查看可用功能
   • 尝试点击列出的命令或键入资源名称以检索资源和提示
   • 该界面允许您测试查询并查看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"
         }
      }
   }
}

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

# 将脚本设为可执行
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

此脚本创建一个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. 在pyproject.toml中添加您的新MCP：

[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