postgres-mcp

一个通用、可复用的 MCP 服务器，用于通过 Claude（或任何兼容 MCP 的客户端）对任何 Postgres 数据库进行只读查询。它不依赖任何特定 schema——list_tables、describe_table 和 run_sql 完全基于 information_schema 和通用的 jsonb 内省机制工作，因此无需修改代码即可指向任何 Postgres 数据库。

安全模型

两个相互独立的层次，形成纵深防御：

1. 数据库层：服务器以一个仅被授予 SELECT 权限的角色连接数据库——即使某条查询试图写入，也不可能成功。请使用 setup_reader_role.sql 创建该角色。

2. 应用层：run_sql() 会拒绝任何不是纯 SELECT（或 WITH ... SELECT）的语句，并在真正访问数据库之前，强制执行 200 行上限和 5 秒的语句超时。

Related MCP server: @yawlabs/postgres-mcp

安装

1. 在目标数据库中创建只读角色：

   • 打开 setup_reader_role.sql，将密码占位符和 <your_db_name> 替换为真实值，然后对数据库执行一次（例如通过 psql 或你的数据库服务商的 SQL 控制台）。

2. 在此目录下的 .env 文件中设置你的连接字符串：

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   （ANTHROPIC_API_KEY 仅用于 chat.py，运行 MCP 服务器本身不需要。）

3. 安装依赖：

   pip install -r requirements.txt

本地测试

首先在没有 MCP 客户端参与的情况下，直接测试查询层：

python chat.py "what tables do I have?"

然后使用 Inspector 将其作为真正的 MCP 服务器进行测试：

fastmcp dev inspector mcp_server.py

如果 Inspector 的 Node 工具链出现问题（之前出现过这种情况），可以改为直接通过 HTTP 运行服务器，并使用 FastMCP Python 客户端访问它：

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

部署（Prefect Horizon）

FastMCP 的托管部署平台目前称为 Prefect Horizon（此前名为 “FastMCP Cloud”——这项服务以前改名过，所以执行前，请先到 gofastmcp.com/deployment 再次确认当前名称/URL，以免它又换了名字）。

1. 将本仓库推送到 GitHub——必须先存在一个真实的远程仓库（如果还没有，请参见本 README 底部的 git 命令）。

2. 打开该平台当前的站点（撰写本文时为 horizon.prefect.io），并使用 GitHub 登录。

3. 连接这个仓库。

4. 配置部署：

   • Entrypoint：mcp_server.py:mcp —— 其中 :mcp 是服务器对象在文件中被赋值的变量名（见 setup 中的 mcp = FastMCP(...) 一行）。如果你以后重命名了该变量或移动文件，此 entrypoint 字符串必须更新以完全匹配。

   • 认证：请务必开启。claude.ai 和 Claude Desktop 等交互式 MCP 客户端需要真正的 OAuth 发现端点才能连接——即使直接使用原始 API 调用或 FastMCP Python 客户端测试正常，没有启用认证的服务器也不会与这些客户端。

   • 环境变量：在平台自己的监控面板中添加 DATABASE_URL。这独立于本项目的本地 .env 文件，并且不会读取该文件——必须直接在 dashboard 中输入值，已部署的服务器才能访问数据库。

5. 部署并复制生成的服务器 URL。它的格式类似 https://<your-server-name>.fastmcp.app/mcp（实际域名可能有差异），以平台实际显示为准）。

6. 在接入任何其他应用之前，先用平台自带的内置 Inspector/测试工具进行测试。首先在其中调用 list_tables——它不需要参数，因此这是确认部署后的服务器能否真正访问你的数据库的最快方式。

连接到 claude.ai

1. 打开 claude.ai → Settings → Connectors → Add custom connector。

2. 粘贴上面部署步骤中生成的服务器 URL。

3. 完成它引导的 OAuth 授权流程。

4. 开启一个新的聊天（而不是该连接器添加之前建立聊天的），并在该聊天中启用这个连接器。

5. 用一个简单的问题测试，例如“what tables do I have?”。

6. 如果之后再添加新工具但没看到工具，先尝试在连接器设置中“Refresh tools”，而不要急着判断出问题——这是一个已知的缓存行为，不是 bug。

限制

这个方案确实与 schema 无关，但并不是没有限制：

• 仅限 Postgres。它使用了 jsonb_object_keys() 和 Postgres 的系统目录语法（information_schema 等）。如果用于 MySQL 或 SQLite，需要对 db_tools.py 进行真正的代码修改，而不只是换一个连接字符串。

• Schema 无关 ≠ 每个数据库零配置。每个新目标数据库仍然需要创建自己的只读角色（setup_reader_role.sql），并专门部署（或至少准备一个指向它的 DATABASE_URL）。这不是一个可以透明地为多个数据库提供服务的单一服务器。

Git 设置

如果你在还没有 git 历史的情况下从这份代码开始：

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main