pgsql-mcp-服务器

Name: pgsql-mcp-服务器
Author: leixiaotian1

作者：leixiaotian111 星标更新：2025-08-24

安装使用来源：spider==github.com

项目介绍

PostgreSQL MCP 服务器

Stars Forks

中文 | English

这是一个提供与PostgreSQL数据库交互工具的模型上下文协议（MCP）服务器。它使AI助手能够通过MCP协议执行SQL查询、解释语句、创建表以及列出数据库表。

✨ 特性

通过AI与数据库交互： 允许大型语言模型（LLMs）通过结构化协议执行数据库操作。
安全工具集： 将读取和写入操作分离成不同的可授权工具（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数据库服务器

安装

克隆仓库：

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

安装依赖：
```
go mod download
```
构建MCP服务器：
```
go build -o pgsql-mcp-server
```

配置

pg-mcp-server需要通过环境变量提供数据库连接详情。在项目根目录创建一个.env文件，包含以下变量：

DB_HOST=localhost      # PostgreSQL服务器主机
DB_PORT=5432           # PostgreSQL服务器端口
DB_NAME=postgres       # 数据库名称
DB_USER=your_username  # 数据库用户名
DB_PASSWORD=your_pass  # 数据库密码
DB_SSLMODE=disable     # SSL模式（disable, require, verify-ca, verify-full）
SERVER_MODE=stdio      # 服务器模式（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 部署

<details> <summary><strong>点击展开Docker部署指南</strong></summary>

预备条件

已安装Docker

部署步骤

克隆项目

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

配置.env文件

在项目根目录创建一个.env文件。该文件存储数据库连接信息。确保DB_HOST值与您稍后启动的数据库容器名称相匹配。
```
DB_HOST=postgres
DB_PORT=5432
DB_NAME=
DB_USER=user
DB_PASSWORD=password
DB_SSLMODE=disable
SERVER_MODE=sse
```
创建Docker网络

为了使应用程序容器和数据库容器之间能够通信，创建一个共享的Docker网络。此命令只需运行一次。
```
docker network create sql-mcp-network
```
启动PostgreSQL数据库容器

使用此命令启动一个PostgreSQL容器并将其连接到我们的网络。
注意：
- --name postgres：容器名称，必须与.env文件中的DB_HOST完全匹配。
- --network sql-mcp-network：连接到共享网络。
- -p 5432:5432：将主机的5432端口映射到容器的5432端口。这意味着您可以从计算机（例如，使用DBeaver）通过localhost:5432连接，而应用容器将通过内部网络直接访问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
```
构建并运行应用程序

现在可以使用Makefile中的命令来管理应用程序。
- 构建镜像并运行容器：
```
make build
make run
```
  这将自动停止旧容器，构建新镜像，并启动新容器。
- 查看应用程序日志：
```
make logs
```
  如果看到Successfully connected to database，则一切正常工作。
- 停止应用程序：
```
make stop
```

</details>

🔌 服务器模式

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

`stdio`

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

`sse`

服务器使用服务端发送事件（SSE）进行通信。当启用此模式时，服务器将启动HTTP服务并监听连接。

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

`streamableHttp`

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

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

🤝 贡献

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

分叉项目。
创建您的功能分支（git checkout -b feature/AmazingFeature）。
提交更改（git commit -m 'Add some AmazingFeature'）。
推送到分支（git push origin feature/AmazingFeature）。
打开Pull Request。

📄 许可证

本项目是开源的，并根据MIT许可证发布。