MCP Server for PostgreSQL

PostgreSQL MCP 服务

用于 PostgreSQL 数据库操作的 MCP 服务。可与 Claude Code、Claude Desktop、Cursor 及任何兼容 MCP 的客户端配合使用。

语言版本

此仓库包含 TypeScript 和 Python 两种实现：

版本	目录	状态	MCP 协议	安装
TypeScript	/typescript	✅ 推荐（Smithery）	2026-07-28（SDK v2）	npm install -g @javiagui/postgresql-mcp
Python	/python	✅ 稳定	2026-07-28（SDK v2）	pipx install postgresql-mcp

注意：Smithery 部署使用 TypeScript 版本。两个版本提供相同的功能。

协议兼容性：两个服务均使用 2026-07-28 修订版，并且兼容两个时代的协议——仍使用 2025 时代 initialize 握手启动的客户端也会像以前一样获得服务，因此无需升级客户端。TypeScript 包需要经过补丁处理的 Node.js 22.23.4 或 24.22.1； Python 包需要 Python 3.11+（CI 使用经过补丁处理的 3.11.17 和 3.12.15）。

功能

• 查询执行：执行 SQL 查询，默认启用只读保护
• 架构探索：列出架构、表、视图和函数
• 表分析：描述结构、索引、约束和统计信息
• 性能工具：执行查询的 EXPLAIN 并分析表的健康状况
• 安全优先：防止 SQL 注入、保护凭据，默认只读
• MCP 提示词：提供用于探索、构建查询和编写文档的引导式工作流
• MCP 资源：以 Markdown 格式浏览数据库结构

快速开始

TypeScript（推荐用于 Smithery）

# Install globally
npm install -g @javiagui/postgresql-mcp

# Or run directly with npx
npx @javiagui/postgresql-mcp

Python

# Install
pipx install postgresql-mcp

# Configure Claude Code
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- postgresql-mcp

完整安装指南 - 包含数据库权限设置、远程连接和故障排除。

配置

环境变量

变量	必填	默认值	说明
POSTGRES_HOST		localhost	数据库主机
POSTGRES_PORT		5432	数据库端口
POSTGRES_USER	✅		数据库用户
POSTGRES_PASSWORD	✅		数据库密码
POSTGRES_DB	✅		数据库名称
POSTGRES_SSLMODE		prefer	SSL 模式
ALLOW_WRITE_OPERATIONS		false	启用 INSERT/UPDATE/DELETE
QUERY_TIMEOUT		30	查询超时时间（秒）
MAX_ROWS		1000	返回的最大行数

多个数据库

大多数实际工作都会涉及多个数据库。无需每次都编辑此配置并重启客户端，只需声明多个连接，然后在每次调用时按别名选择：

POSTGRES_CONNECTIONS='[
  {"alias":"local","host":"localhost","user":"me","password":"…","database":"app","allowWrite":true},
  {"alias":"staging","url":"postgresql://reader:…@staging.example.com:5432/app"},
  {"alias":"analytics","url":"postgresql://reader:…@warehouse:6543/metrics?sslmode=require","default":true}
]'

• **list_databases**会返回已配置的别名，以及主机、数据库名称、写入权限和默认连接信息。绝不会返回凭据。
• 除此之外的每个工具都接受可选的**database**参数，用于指定别名。省略该参数时，将使用默认连接，因此现有的单数据库配置无需任何更改即可继续使用。
• allowWrite按连接设置，未设置时回退到ALLOW_WRITE_OPERATIONS。生产副本保持只读，而本地数据库允许写入。
• default: true用于标记省略database时使用的连接；如果未标记，则使用第一个声明的连接。最多只能有一个连接标记为默认。
• 每个连接可使用独立字段（host、port、user、password、database、sslmode）或url DSN；独立字段会覆盖 DSN，因此你可以复用 URL 并修改其中一部分。
• 每个别名对应一个连接池，按需延迟打开：已配置但未使用的数据库不会建立套接字连接。

POSTGRES_CONNECTIONS与普通的POSTGRES_*变量互斥。设置前者时会忽略其他变量，因此不会出现无法确定哪个配置生效的情况。

凭据始终只能来自环境变量。database参数用于指定别名；有意不提供通过工具参数传递主机、用户、密码或连接字符串的方式，因为这会让机密进入对话。此规则由测试强制执行。

Claude Code CLI

# TypeScript version
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- npx @javiagui/postgresql-mcp

# Python version
claude mcp add postgres -s user \
  -e POSTGRES_HOST=localhost \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=your_database \
  -- postgresql-mcp

Cursor IDE

添加到~/.cursor/mcp.json：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@javiagui/postgresql-mcp"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_user",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DB": "your_database"
      }
    }
  }
}

可用工具（共 15 个）

除list_databases外，以下每个工具都接受可选的database参数，用于指定已配置的连接——参见多个数据库。

查询执行

工具	描述
query	对数据库执行只读 SQL 查询
execute	在启用时执行写入操作（INSERT/UPDATE/DELETE）
explain_query	获取查询的 EXPLAIN 计划以优化查询

架构探索

工具	描述
list_schemas	列出数据库中的所有架构
list_tables	列出指定架构中的表
describe_table	获取表结构（列、类型、约束）
list_views	列出架构中的视图
describe_view	获取视图定义和列
list_functions	列出函数和过程

性能与分析

工具	描述
table_stats	获取表统计信息（行数、大小、膨胀情况）
list_indexes	列出表的索引
list_constraints	列出约束（PK、FK、UNIQUE、CHECK）

数据库信息

工具	描述
get_database_info	获取数据库版本和连接信息
search_columns	在所有表中按名称搜索列
list_databases	按别名列出已配置的连接，以及主机、数据库、写入权限和默认连接信息。绝不返回凭据。

MCP 提示词

引导式工作流，帮助 Claude 高效地协助你：

提示词	描述
explore_database	全面探索数据库并概述其内容
query_builder	帮助为表构建高效查询
performance_analysis	分析表性能并提出优化建议
data_dictionary	为架构生成文档

MCP 资源

可浏览的数据库结构：

资源 URI	描述
postgres://schemas	列出所有架构
postgres://schemas/{schema}/tables	架构中的表
postgres://schemas/{schema}/tables/{table}	表详情
postgres://database	数据库连接信息

示例用法

配置完成后，请 Claude 执行以下操作：

架构探索：

• “列出 public 架构中的所有表”
• “描述 users 表的结构”
• “有哪些视图可用？”

查询：

• “显示 orders 表中的 10 行数据”
• “查找上周下单的所有客户”
• “按状态分组统计记录数”

性能分析：

• “orders 表上有哪些索引？”
• “分析 users 表的性能”
• “解释此查询：SELECT * FROM orders WHERE created_at > '2024-01-01'”

文档：

• “为此数据库生成数据字典”
• “哪些列的名称中包含 ‘email’？”

安全性

此 MCP 服务采用多层安全防护：

默认只读

除非通过 ALLOW_WRITE_OPERATIONS=true 明确启用，否则会阻止写入操作（INSERT、UPDATE、DELETE）。

SQL 注入防护

• 执行前会验证所有查询
• 始终阻止危险操作（DROP DATABASE 等）
• 不允许执行多条语句
• 禁止 SQL 注释

凭据保护

• 使用安全字符串类型存储密码
• 凭据绝不会出现在日志或错误消息中

查询限制

• 使用 MAX_ROWS 限制结果数量（默认值：1000）
• 可通过 QUERY_TIMEOUT 配置查询超时时间

开发

TypeScript

cd typescript
npm install
npm run build
npm run dev  # Watch mode

Python

cd python
uv sync
uv run pytest -v --cov=postgres_mcp

运行测试

# Python unit tests (no database required)
cd python
uv run pytest tests/test_security.py tests/test_settings.py -v

# Integration tests (requires PostgreSQL)
docker-compose up -d
uv run pytest tests/test_integration.py -v

故障排除

连接问题

# Verify PostgreSQL is running
pg_isready -h localhost -p 5432

# Test connection with psql
psql -h localhost -U your_user -d your_database

权限被拒绝

确保数据库用户拥有 SELECT 权限：

GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;

MCP 服务无法连接

# Check server status
claude mcp get postgres

# Test server directly
postgresql-mcp  # Should wait for MCP messages

链接

• PyPI 软件包
• npm 软件包
• 安装指南
• GitHub 仓库

作者

由 Javier Aguilar 构建，他是一位专注于多 Agent 编排和 MCP 开发的 AI Agent 架构师。

许可证

MIT