PostgreSQL MCP Server

PostgreSQL MCP 服务

一个 Python Model Context Protocol（MCP）服务，用于通过兼容 MCP 的客户端检查和查询 PostgreSQL 数据库。它提供架构发现、安全的只读查询执行、查询计划说明、表预览、索引分析、关系检查，以及用于获取表元数据的 PostgreSQL 资源。

功能

• 列出 public 架构中的表并检查表架构
• 在 PostgreSQL 只读事务中执行只读 SQL
• 说明查询计划，而不直接执行目标查询
• 以固定行数上限预览表数据
• 检查外键关系和索引
• 提供用于获取表列表和架构详情的被动 MCP 资源

安全模型

postgresql_execute_read_query 以 PostgreSQL 只读事务模式运行，通过 POSTGRES_READ_QUERY_LIMIT 限制返回行数，并在执行后回滚。服务还包含 postgresql_execute_write_query，它只接受单条 INSERT、UPDATE、DELETE、CREATE、ALTER、DROP 或 TRUNCATE 语句；如果连接的数据库用户拥有相应权限，该工具可以修改数据或架构。请勿在 MCP 客户端中自动批准具有写入能力的工具。对于公开或共享用途，请使用专用的 PostgreSQL 只读用户运行服务。

要求

• Python 3.11+
• PostgreSQL 数据库
• 兼容 MCP 的客户端，例如 Claude Desktop、Cursor、VS Code 或其他 MCP 宿主

安装

发布到 PyPI 后，可像安装标准 Python MCP 软件包一样安装或运行此服务：

uvx mdev-postgresql-mcp-server

从源代码进行本地开发：

git clone https://github.com/musaddiq-dev/postgresql-mcp-server.git
cd postgresql-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

复制示例环境文件，并填写数据库连接详情。

cp .env.example .env

变量	描述	必需	默认值
POSTGRES_HOST	PostgreSQL 主机	是	localhost
POSTGRES_PORT	PostgreSQL 端口	是	5432
POSTGRES_USER	PostgreSQL 用户名	是	无
POSTGRES_PASSWORD	PostgreSQL 密码	否	无
POSTGRES_DB	PostgreSQL 数据库名称	是	无
LOG_LEVEL	写入 stderr 的 Python 日志级别	否	INFO
POSTGRES_READ_QUERY_LIMIT	只读查询返回的最大行数	否	1000

只读用户示例：

CREATE USER mcp_readonly WITH PASSWORD 'change-me';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

运行

mdev-postgresql-mcp-server

在 PyPI 发布前，从本地检出目录运行：

python -m postgresql_mcp_server.server

MCP 客户端配置

对于已发布的软件包，建议使用 uvx。使用 stdio 的 MCP 服务必须只向 stdout 写入协议消息；此服务通过 Python 日志记录将日志写入 stderr。

Claude Desktop / Cursor / Windsurf / Cline

大多数 MCP 客户端接受以下 mcpServers JSON 格式：

{
  "mcpServers": {
    "postgresql": {
      "command": "uvx",
      "args": ["mdev-postgresql-mcp-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

在此仓库中进行本地开发时，请改用已安装的控制台脚本路径：

{
  "mcpServers": {
    "postgresql": {
      "command": "/absolute/path/to/postgresql-mcp-server/.venv/bin/mdev-postgresql-mcp-server",
      "args": [],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

Claude Code CLI

claude mcp add postgresql \
  --env POSTGRES_HOST=localhost \
  --env POSTGRES_PORT=5432 \
  --env POSTGRES_USER=mcp_readonly \
  --env POSTGRES_PASSWORD=change-me \
  --env POSTGRES_DB=your_database \
  -- uvx mdev-postgresql-mcp-server

VS Code MCP

VS Code 在其 MCP 配置中使用相同的 command/args/env 模式：

{
  "servers": {
    "postgresql": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mdev-postgresql-mcp-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "mcp_readonly",
        "POSTGRES_PASSWORD": "change-me",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

工具

工具	用途	安全性
postgresql_list_tables	列出 public 架构中的基础表	只读
postgresql_describe_table	显示表的列和元数据	只读
postgresql_execute_read_query	在只读事务模式下执行有行数限制的 SQL	只读
postgresql_execute_write_query	执行并提交单条获准的修改类 SQL 语句	具有破坏性
postgresql_explain_query	返回单条查询的 PostgreSQL EXPLAIN 输出	只读
postgresql_get_database_summary	返回数据库版本和表数量	只读
postgresql_get_relationships	检查外键关系	只读
postgresql_analyze_indexes	检查索引及其大小	只读
postgresql_preview_table	返回表中最多 10 行数据	只读
postgresql_search_sql_definitions	搜索 public 架构中的 SQL 例程/函数	只读

资源

• postgres://list_tables 返回 public 架构中的表名。
• postgres://schema/{table_name} 返回为某个表生成的架构语句。

冒烟检查

无需数据库即可验证语法：

python -m py_compile src/postgresql_mcp_server/server.py

配置好数据库后，启动服务并使用 MCP 客户端调用 list_tables。

分发

此服务通过标准 Python MCP 分发渠道发布：

• PyPI 软件包：mdev-postgresql-mcp-server
• MCP Registry 名称：io.github.musaddiq-dev/postgresql-mcp-server
• 运行时提示：uvx
• 传输方式：stdio

此 README 顶部的 mcp-name 标记是通过 MCP Registry 所有权验证的必要条件。用户在本地 MCP 客户端配置中应优先使用 uvx mdev-postgresql-mcp-server。

安全说明

• 请勿提交包含凭据的 .env 文件或 MCP 客户端配置。
• 使用遵循最小权限原则的数据库用户。
• 将 execute_write_query 视为具有破坏性的操作，并要求用户在 MCP 客户端中明确批准。
• 运行可执行写入操作的工具前，请检查生成的 SQL。

许可证

MIT