PostgreSQL MCP Server

PostgreSQL MCP 服务

中文 | 英文

一个用于与 PostgreSQL 数据库交互的 Model Context Protocol（MCP）服务。它支持 AI 助手通过 MCP 协议执行 SQL 查询、解释语句、创建表和列出数据库表。

✨ 功能

• 通过 AI 与数据库交互： 支持大模型通过结构化协议执行数据库操作。
• 安全的工具集： 将读写操作分为独立且可授权的工具（read_query、write_query）。
• 架构管理： 支持创建表（create_table）和列出表（list_tables）。
• 查询分析： 提供分析查询执行计划的工具（explain_query）。
• 多种传输模式： 支持 stdio、服务器发送事件（sse）和 streamableHttp，便于灵活集成客户端。
• 基于环境变量的配置： 可使用 .env 文件轻松配置。

🛠️ 可用工具

该服务提供以下工具，供 MCP 客户端调用：

工具名称	描述	参数
read_query	执行 SELECT SQL 查询。	query（字符串，必填）：要执行的 SELECT 语句。
write_query	执行 INSERT、UPDATE 或 DELETE SQL 查询。	query（字符串，必填）：要执行的 INSERT/UPDATE/DELETE 语句。
create_table	执行 CREATE TABLE SQL 语句。	schema（字符串，必填）：CREATE TABLE 语句。
list_tables	列出数据库中所有由用户创建的表。	schema（字符串，可选）：用于筛选表的架构名称。
explain_query	返回指定 SQL 查询的执行计划。	query（字符串，必填）：要解释的查询（必须以 EXPLAIN 开头）。

🚀 快速开始

前提条件

• Go 1.23 或更高版本
• PostgreSQL 数据库服务

安装

1. 克隆仓库：

   git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
   cd pgsql-mcp-server
   

2. 安装依赖：

   go mod download
   

3. 构建 MCP 服务：

   go build -o pgsql-mcp-server
   

配置

pg-mcp-server 需要通过环境变量提供数据库连接信息。在项目根目录创建 .env 文件，并设置以下变量：

DB_HOST=localhost      # PostgreSQL server host
DB_PORT=5432           # PostgreSQL server port
DB_NAME=postgres       # Database name
DB_USER=your_username  # Database user
DB_PASSWORD=your_pass  # Database password
DB_SSLMODE=disable     # SSL mode (disable, require, verify-ca, verify-full)
SERVER_MODE=stdio      # Server mode (stdio, sse, streamableHttp)

使用

运行服务

./pgsql-mcp-server

MCP 配置

要将此服务与支持 MCP 的 AI 助手配合使用，请将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "pgsql-mcp-server": {
      "command": "/path/to/pgsql-mcp-server",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "postgres",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_SSLMODE": "disable",
        "SERVER_MODE": "stdio"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

---

DOCKER 部署

点击展开 Docker 部署指南

前提条件

• 已安装 Docker

部署步骤

1. 克隆项目

   git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
   cd pgsql-mcp-server
   

2. 配置 .env 文件

   在项目根目录中创建一个 .env 文件。该文件用于存储数据库连接信息。请确保 DB_HOST 的值与稍后启动的数据库容器名称一致。

   DB_HOST=postgres
   DB_PORT=5432
   DB_NAME=postgres
   DB_USER=user
   DB_PASSWORD=password
   DB_SSLMODE=disable
   SERVER_MODE=sse
   

3. 创建 Docker 网络

   为了让应用容器和数据库容器能够通信，请创建一个共享的 Docker 网络。此命令只需运行一次。

   docker network create sql-mcp-network
   

4. 启动 PostgreSQL 数据库容器

   使用此命令启动 PostgreSQL 容器，并将其连接到我们的网络。

   注意：

   • --name postgres：容器名称，必须与 .env 文件中的 DB_HOST 完全一致。
   • --network sql-mcp-network：连接到共享网络。
   • -p 5432:5432：将主机的 5432 端口映射到容器的 5432 端口。这意味着你可以通过 localhost:5432 从计算机连接（例如使用 DBeaver），而应用容器则会通过内部网络直接访问 5432 端口。

   docker run -d \
     --name postgres \
     --network sql-mcp-network \
     -e POSTGRES_USER=user \
     -e POSTGRES_PASSWORD=password \
     -e POSTGRES_DB=postgres \
     -p 5432:5432 \
     postgres
   

5. 构建并运行应用

   现在，你可以使用 Makefile 中的命令来管理应用。

   • 构建镜像并运行容器：

     make build
     make run
     

     这将自动停止旧容器、构建新镜像并启动新容器。

   • 查看应用日志：

     make logs
     

     如果看到 Successfully connected to database，说明一切正常。

   • 停止应用：

     make stop
     

---

🔌 服务模式

你可以通过设置 SERVER_MODE 环境变量来选择传输协议。

stdio

服务通过标准输入和输出进行通信。这是默认模式，非常适合本地测试或与基于命令行的 MCP 客户端直接集成。

sse

服务使用 Server-Sent Events（SSE）进行通信。启用此模式后，服务将启动 HTTP 服务并监听连接。

• SSE 端点： http://localhost:8088/sse
• 消息端点： http://localhost:8088/message

streamableHttp

服务使用 Streamable HTTP 传输，这是适用于 MCP 的一种更现代、更灵活的基于 HTTP 的传输方式。

• 端点： http://localhost:8088/mcp

🤝 参与贡献

欢迎贡献！如果你发现任何错误、有功能需求或改进建议，请随时提交 Pull Request 或创建 Issue。

1. Fork 项目。
2. 创建功能分支（git checkout -b feature/AmazingFeature）。
3. 提交更改（git commit -m 'Add some AmazingFeature'）。
4. 推送到分支（git push origin feature/AmazingFeature）。
5. 创建 Pull Request。

📄 许可证

本项目为开源项目，采用 MIT 许可证。