postgresql-mcp-server

# PostgreSQL MCP Server [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com/astral-sh/uv) [](https://modelcontextprotocol.io/) 一个面向 PostgreSQL 的 Model Context Protocol (MCP) 服务。它基于 FastMCP 和 psycopg 构建，通过环境变量连接 PostgreSQL server，并以 **database + schema 双层白名单** 控制 MCP 客户端可以访问的范围。 PostgreSQL 的访问层级是： ```text PostgreSQL server / cluster └── database └── schema └── table / view / index / function ... ``` 因此本服务的当前上下文也是： ```text current_database + current_schema ``` 切换 database 时会重新建立连接；切换 schema 时会在当前 database 内设置 `search_path`。 ## 功能特性 - 🚀 **面向 PostgreSQL server 的多 database 访问**：允许在配置白名单内切换 database。 - 🗂️ **database + schema 双层白名单**：每个 database 都有独立的 schema 白名单。 - 🔐 **安全的 search_path 设置**：使用 psycopg 的 `Identifier` 处理 schema 名，避免手写拼接风险。 - 🧰 **清晰的 MCP 工具前缀**：所有工具均以 `pg_` 开头，便于和其他 MCP 服务共存。 - 👁️ **只读模式**：设置 `POSTGRES_READ_ONLY=true` 后，仅允许 `SELECT`、`WITH`、`EXPLAIN`、`SHOW`。 - 🛡️ **SQL 安全审计**：阻止多语句、注释注入、跨 schema 访问、权限变更、函数/过程/触发器/扩展等高风险操作。 - 📚 **常用元数据工具**：支持列出 database、schema、表，描述表结构，统计表数量。 - 📄 **分页查询**：`pg_execute_sql` 对 `SELECT/WITH` 支持 `limit` 和 `offset`。 ## 工具列表 | 工具 | 说明 | | :-- | :-- | | `pg_test_connection` | 测试当前 database + schema 上下文是否可连接。 | | `pg_get_current_context` | 返回当前 database、schema、允许的 database、当前 database 下允许的 schema。 | | `pg_list_databases` | 列出配置允许访问的 database，并标记当前 database。 | | `pg_switch_database` | 切换当前 database，可选同时切换目标 database 下的 schema。 | | `pg_list_schemas` | 列出指定 database 或当前 database 中可见的非系统 schema。 | | `pg_switch_schema` | 在当前 database 内切换当前 schema。 | | `pg_execute_sql` | 在当前上下文执行 SQL。查询返回 `data` 和 `count`，写入返回 `affected_rows`。 | | `pg_list_tables` | 列出指定 database/schema 或当前上下文下的表和视图。 | | `pg_d…