Postgres Readonly MCP

PostgreSQL只读MCP服务器

一种模型上下文协议（MCP）服务器，提供对PostgreSQL数据库的安全、只读访问。

此服务器向MCP客户端（如Claude Desktop）公开数据库工具（列表表、描述模式、预览行、运行只读查询、显示关系、统计数据）。

这个项目解决了什么

当人工智能工具需要数据库上下文时，直接访问SQL可能会有风险。 此服务器添加了一个受控层：

• 只读查询验证
• 基于工具的模式和数据访问
• 查询结果限制和超时保护
• 多数据库支持(db 和 db2)
• 山宁泰错误消息（已编辑凭据）

特性

• PostgreSQL的严格只读访问(SELECT 仅）
• 表和模式检查
• 具有行和文本截断限制的数据预览
• 外键关系发现
• 数据库级统计信息（大小、行估计数、最大表）
• 两个逻辑数据库目标： db （主要）和 db2 （次要）

项目结构

src/index.ts -MCP服务器入口点和工具注册\ src/connection-manager.ts -连接池、环境解析、查询执行\ src/query-validator.ts -只读验证规则\ src/tools/*.ts -工具实现

需求

• Node.js 18+
• npm
• 从您的计算机访问PostgreSQL网络

安装

git clone 
cd postgres-readonly-mcp
npm install
npm run build

快速入门（逐步）

1） 配置环境

创建一个 .env 项目根目录中的文件。

你可以使用其中一种模式。

选项A：两者都有一个URL db 和 db2

DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DB_NAME?schema=public

选项B：单独的主机字段（为清楚起见建议使用）

# Primary database (db)
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=your_database
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true

# Secondary database (db2)
DB2_HOST=127.0.0.1
DB2_PORT=5432
DB2_USER=postgres
DB2_PASSWORD=your_password
DB2_NAME=your_database_2
DB2_SSL=true
DB2_SSL_REJECT_UNAUTHORIZED=true

选项C：单独的URL

DB_URL=postgresql://USER:PASSWORD@HOST:5432/DB1
DB2_URL=postgresql://USER:PASSWORD@HOST:5432/DB2

2） 构建

npm run build

3） 快跑

npm start

开发模式：

npm run dev

4） 从克劳德桌面连接

将此添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "node",
      "args": ["/absolute/path/to/postgres-readonly-mcp/dist/index.js"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "DB_SSL": "true",
        "DB_SSL_REJECT_UNAUTHORIZED": "true",
        "DB2_HOST": "127.0.0.1",
        "DB2_PORT": "5432",
        "DB2_USER": "postgres",
        "DB2_PASSWORD": "your_password",
        "DB2_NAME": "your_database_2",
        "DB2_SSL": "true",
        "DB2_SSL_REJECT_UNAUTHORIZED": "true"
      }
    }
  }
}

编辑配置后重新启动Claude Desktop。

环境变量参考

核心变量

• DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME ->主要连接(db)
• DB2_HOST, DB2_PORT, DB2_USER, DB2_PASSWORD, DB2_NAME ->次级连接(db2)
• DB_SSL, DB_SSL_REJECT_UNAUTHORIZED ->TLS设置 db
• DB2_SSL, DB2_SSL_REJECT_UNAUTHORIZED ->TLS设置 db2
• DATABASE_URL ->两个数据库的回退URL
• DB_URL, DB2_URL ->每个数据库的显式URL
• DB_DATABASE_URL, DB2_DATABASE_URL ->还支持别名URL名称

DB_SSL 默认为 true 在严格模式下。

决议优先级

对于 db:

1. DB_* 领域
2. DB_URL 或 DB_DATABASE_URL
3. DATABASE_URL
4. 默认值(localhost, 5432, postgres、空密码， postgres)

对于 db2:

1. DB2_* 领域
2. DB2_URL 或 DB2_DATABASE_URL
3. DATABASE_URL
4. 回退到已解决 db 价值观

URL编码说明

如果您的密码包含特殊字符(/, @, :)，URL将其编码为连接字符串。

例子：

• 真实密码： my/pass
• 在URL中： my%2Fpass

DATABASE_URL=postgresql://postgres:my%2Fpass@127.0.0.1:5432/your_database?schema=public

工具参考

所有工具均接受可选 database 值：

• db （默认）
• db2

1) list_tables

列出架构中的表/视图。

输入：

{
  "database": "db",
  "schema": "public"
}

返回以下数组：

• name
• type (BASE TABLE 或 VIEW)
• rowCount （估计）
• schema

2) describe_table

描述列、主键、外键和索引。

输入：

{
  "database": "db",
  "schema": "public",
  "table": "Mail"
}

3) preview_data

使用可选的列选择预览表中的行。

输入：

{
  "database": "db",
  "schema": "public",
  "table": "Mail",
  "columns": ["id", "subject", "createdAt"],
  "limit": 10
}

4) run_query

运行自定义只读SQL查询。

输入：

{
  "database": "db",
  "query": "SELECT id, subject FROM \"public\".\"Mail\" ORDER BY id DESC",
  "limit": 100
}

5) show_relations

显示表的外键关系（传入和传出）。

输入：

{
  "database": "db",
  "schema": "public",
  "table": "Mail"
}

6) db_stats

获取数据库大小和表统计信息。

输入：

{
  "database": "db"
}

退货：

• database
• totalTables
• totalRows
• totalSize
• largestTables

只读和安全规则

允许的语句类型

• SELECT

被屏蔽的关键字（示例）

• INSERT, UPDATE, DELETE
• DROP, ALTER, TRUNCATE, CREATE
• GRANT, REVOKE, LOCK
• COPY, VACUUM, ANALYZE, REINDEX, CLUSTER

额外的严格模式检查

• 一个请求中的多个SQL语句被阻止
• 某些有风险的函数调用被阻止（例如 pg_sleep, dblink，文件读取功能）
• 最后一行上限是在服务器端强制执行的，即使您的SQL包含更大的行上限 LIMIT

执行限制

• preview_data 违约： 10，最大值： 100
• run_query 违约： 1000，最大值： 5000
• 查询超时： 30s (statement_timeout 和 query_timeout)
• 长文本截断： 200 字符

错误安全

对连接和运行时错误进行清理，以防止凭据泄漏。

常见用法示例

示例1：列出所有公共表

使用 list_tables 与：

{ "database": "db", "schema": "public" }

示例2：预览最近的邮件

使用 run_query 与：

{
  "database": "db",
  "query": "SELECT id, subject, \"createdAt\" FROM \"public\".\"Mail\" ORDER BY \"createdAt\" DESC",
  "limit": 20
}

示例3：比较两个数据库

1. 呼叫 db_stats 随着 database: "db"
2. 呼叫 db_stats 随着 database: "db2"
3. 比较 totalTables, totalRows，以及 largestTables

发展

# Type-check and compile
npm run build

# Run server in dev mode
npm run dev

# Start compiled server
npm start

# Run tests
npm test

发布到npm

# Patch release (1.0.0 -> 1.0.1)
npm run release

# Minor release (1.0.0 -> 1.1.0)
npm run release:minor

# Major release (1.0.0 -> 2.0.0)
npm run release:major

# Validate flow without changing anything
npm run release:dry-run

发布脚本行为：

• 需要一个干净的git工作树
• 用途 npm version 升级版本（创建提交和标记）
• 跑动 npm publish --access public （构建通过 prepublishOnly)

故障排除

连接失败

• 验证主机/端口是否可以从您的计算机访问。
• 验证用户名/密码和数据库名称。
• 如果使用URL，请确保密码中的特殊字符是URL编码的。

服务器已启动，但客户端中没有工具

• 确认客户点是否正确 dist/index.js 路径。
• 配置更改后重新启动客户端应用程序。
• 检查stderr日志中的启动错误。

查询被拒绝

• 查询可能包含被阻止的关键字或不支持的语句类型。
• 重写为严格只读查询(SELECT 仅）。

许可证

麻省理工学院