Secure Schema MCP

Secure Schema MCP

一个只读 MCP 服务，向 AI 编码工具提供数据库结构，但不暴露行数据。它以紧凑格式返回表和视图名称、列、类型、键和关系，旨在减少 LLM 令牌用量。

暴露的内容

暴露	不暴露
表和视图名称	行值或查询结果
列名称和 SQL 类型	行数或样本
主键和唯一键	数据库凭据
外键关系	写入或查询工具

架构元数据仍可能包含敏感信息。即使没有值，像 ssn 这样的列名也会泄露信息，因此生产部署应始终使用表白名单和专用数据库账户。

要求

• 兼容 MCP 的客户端，例如 Cursor 或 Codex
• 可访问的 SQLite、PostgreSQL 或 MySQL 数据库
• 不使用 uvx 安装时，需要 Python 3.12 或更高版本

SQLite 支持使用 Python 内置驱动。PostgreSQL 和 MySQL 驱动已包含在内。其他 SQLAlchemy 方言在 v1 中未经测试，也未随包提供。

配置 IDE

推荐的设置方式使用 uvx 下载并在隔离环境中运行已发布的 Python 包。无需克隆此仓库，也无需单独启动服务。IDE 会在需要时通过 stdio 启动它。

Cursor

将此服务添加到 Cursor MCP 配置中：

{
  "mcpServers": {
    "secure-schema": {
      "command": "uvx",
      "args": ["mcp-secure-schema"],
      "env": {
        "DATABASE_URL": "postgresql+psycopg2://schema_reader:password@localhost:5432/appdb",
        "DATABASE_SCHEMA": "public",
        "ALLOWED_TABLES": "users,orders,products",
        "SECURE_SCHEMA_ENV": "production",
        "FASTMCP_CHECK_FOR_UPDATES": "off",
        "FASTMCP_SHOW_SERVER_BANNER": "false"
      }
    }
  }
}

更改 MCP 配置后，重启或重新加载 Cursor。

Codex

将以下内容添加到 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 中：

[mcp_servers.secure-schema]
command = "uvx"
args = ["mcp-secure-schema"]
enabled_tools = ["schema_overview", "list_tables", "inspect_table"]
startup_timeout_sec = 30
tool_timeout_sec = 30

[mcp_servers.secure-schema.env]
DATABASE_URL = "postgresql+psycopg2://schema_reader:password@localhost:5432/appdb"
DATABASE_SCHEMA = "public"
ALLOWED_TABLES = "users,orders,products"
SECURE_SCHEMA_ENV = "production"
FASTMCP_CHECK_FOR_UPDATES = "off"
FASTMCP_SHOW_SERVER_BANNER = "false"

改为一次性安装

如果你更喜欢持久安装：

pipx install mcp-secure-schema

然后在 IDE 配置中使用 "command": "mcp-secure-schema"，并将 args 列表设为空。

数据库 URL

Secure Schema MCP 接受 SQLAlchemy 连接 URL：

# SQLite (absolute path)
sqlite:////Users/me/project/app.db

# PostgreSQL
postgresql+psycopg2://user:password@localhost:5432/appdb

# Remote PostgreSQL with certificate verification
postgresql+psycopg2://user:[email protected]:5432/appdb?sslmode=verify-full&sslrootcert=/path/to/ca.pem

# MySQL
mysql+pymysql://user:password@localhost:3306/appdb

对 URL 中的用户名和密码里的特殊字符进行百分号编码。例如，密码中的 @ 应写作 %40。

本地和远程数据库使用相同的 MCP 配置。对于远程数据库，运行 IDE 的机器还必须具备正常的 DNS、网络访问、防火墙权限和有效的 TLS 设置。

配置

变量	必需	说明
DATABASE_URL	是	SQLAlchemy 连接 URL。在注册表清单中视为机密。
DATABASE_SCHEMA	否	默认架构或目录命名空间。建议用于 PostgreSQL。在生产环境中禁止通过工具覆盖。
ALLOWED_TABLES	生产环境	以逗号分隔、区分大小写的表和视图白名单。生产模式下未设置此项时将拒绝启动。
SECURE_SCHEMA_ENV	否	设置为 production 或 prod，以启用严格的启动验证。默认为 development。
FASTMCP_CHECK_FOR_UPDATES	否	设置为 off，以确保 stdio 启动行为可预测。
FASTMCP_SHOW_SERVER_BANNER	否	设置为 false，以隐藏启动横幅。

多个架构

DATABASE_SCHEMA 用于选择默认命名空间。解析规则如下：

• 在生产环境中，已配置的 DATABASE_SCHEMA 是一道安全边界，工具参数不能覆盖它。
• 在非生产环境中，显式的工具 schema 参数会覆盖 DATABASE_SCHEMA。
• 两者都未设置时，将使用数据库驱动的默认架构。

如需在生产环境中严格访问多个架构，请为每个架构配置一个 MCP 服务条目，并分别设置 DATABASE_SCHEMA 和 ALLOWED_TABLES。表白名单使用未限定名称，而非 schema.table 值。

工具

• schema_overview：获准访问的表、视图、主键和外键关系的紧凑映射
• list_tables：获准访问的表和视图清单
• inspect_table：单个实体的列、SQL 类型、是否可为空、主键、唯一约束和外键

所有工具默认使用 format="compact"，以减少令牌用量：

tables:orders,users | pk:orders(order_id);users(user_id) | fk:orders.user_id->users.user_id

需要更便于人阅读的表格时，请传入 format="markdown"。

安全说明

• 服务仅公开 SQLAlchemy 检查操作；不提供行查询或写入工具。
• 启用允许列表时，不存在的表名和不允许的表名会返回相同消息，以避免泄露表是否存在。
• 面向客户端的错误信息经过清理。操作详情会写入服务的标准错误流。
• IDE 会启动 MCP 进程并提供其环境，因此请将 IDE 及其配置视为可信对象。
• 请勿提交包含凭据的配置。如需更强的隔离，请通过包装脚本启动，并从操作系统密钥链或密钥管理器获取 DATABASE_URL。
• 远程连接请使用遵循最小权限原则的专用数据库账户，并验证 TLS 证书。

PostgreSQL 角色示例：

CREATE ROLE schema_reader LOGIN PASSWORD 'use-a-secret-manager';
GRANT CONNECT ON DATABASE appdb TO schema_reader;
GRANT USAGE ON SCHEMA public TO schema_reader;

元数据的可见性因 PostgreSQL 提供商和数据库策略而异。仅授予检查所需的额外目录或对象权限；除非环境有要求，否则避免授予行级 SELECT 权限。

故障排除

服务立即退出

检查 IDE 的 MCP 日志。DATABASE_URL 为必填项，生产模式还要求 ALLOWED_TABLES 的值非空。

未发现任何表或视图

确认 DATABASE_SCHEMA、表名的大小写是否完全一致、数据库权限，以及允许列表是否包含预期名称。

连接 URL 使用有效密码却仍然失败

对 URL 中的保留字符进行百分号编码，或使用密钥注入包装脚本。请勿在问题或日志中粘贴真实凭据。

找不到 uvx

按照 uv 的官方说明进行安装，或使用 pipx 安装此软件包，并将 mcp-secure-schema 用作命令。

启动命令时似乎卡住

这是 stdio MCP 服务的正常行为。它会等待标准输入中的 MCP 客户端，通常由 IDE 启动。

开发

仅在开发或测试服务时克隆仓库：

git clone https://github.com/Siddharth-coder13/secure_schema_mcp.git
cd secure_schema_mcp
uv sync --extra dev
uv run python tests/demo_database.py
DATABASE_URL="sqlite:///$PWD/test_schema.db" uv run mcp-secure-schema

运行测试套件：

uv run pytest

针对一次性数据库运行选择性启用的 PostgreSQL 集成测试。该测试会创建并删除一个随机命名的架构：

POSTGRES_TEST_DATABASE_URL='postgresql+psycopg2://user@localhost:5432/testdb' \
  uv run pytest tests/test_postgres_smoke.py -v

测试会验证行数据隔离、允许列表行为、已清理的错误信息、紧凑输出、关系、架构选择，以及锁定的生产命名空间。

发布检查清单

维护者应更新 pyproject.toml 和 server.json 中对应的版本，运行完整的 SQLite 和 PostgreSQL 测试套件，使用 uv build --no-sources 构建，验证从 wheel 安装，然后发布到 PyPI，最后再将 server.json 发布到 MCP Registry。

许可证

根据 Apache License 2.0 授权。请参阅 LICENSE 和 NOTICE。