SQL Safe MCP

sql-safe-mcp

面向使用 SQL Server、MySQL 和 MariaDB 的编码 Agent 的 PII 安全只读 MCP 服务： 提供架构知识和安全查询，不提供可写入的工具，也不会以明文形式暴露配置为 PII 的列。

读取数据，保护身份。

为编码 Agent 提供编写正确代码所需的架构知识，包括服务、数据库、表、列、键、索引和存储过程。在标记为 all_pii_safe 的别名上，它还可以查询真实行，同时将配置的个人数据隐藏在经过身份验证的令牌之后。

默认保障 PII 安全，设计上只读。

• 默认保障 PII 安全 - 在 all_pii_safe 服务上，配置的列会以绑定别名且经过身份验证的令牌（pii:v1:...）返回，绝不会以明文形式返回。Agent 仍可使用已获得的令牌，通过 = 和 IN 对这些列进行投影、计数和筛选，从而追踪记录而不读取其内容。令牌无法用于其他服务别名或其他密钥。
• 从设计上只读 - 提供七种工具，且全部标注为只读。没有工具会写入数据，服务也绝不会执行 Agent 编写的 SQL：元数据来自 SQLAlchemy Inspector 和固定的目录查询，而 execute_sql 只会运行经过验证并重新生成的 SELECT。
• 多个服务，策略彼此隔离 - 一个 MCP 进程可以提供多个命名的 SQL Server、MySQL 和 MariaDB 实例。每个别名都有自己的连接和访问级别；启用 PII 保护时，也有自己的 PII 密钥和保护规则。每项数据库操作都针对明确指定的别名；不会进行网络发现。

运行安全措施

• 失败时默认拒绝 — SQL 验证采用允许列表。遇到未知语法、无法解析的血缘关系和不受支持的受保护值类型时，会拒绝执行，而不会自行猜测。验证证据见安全模型。
• 先采用最低访问权限 — access_level: metadata（默认值）可查看数据库导航信息和表结构；meta_and_code 还可查看存储过程；execute_sql 则需要显式配置带有独立密钥的 all_pii_safe 别名。数据库权限仍是首要控制措施，因此请使用遵循最小权限原则的登录账号。
• 保密信息不会泄露 — 连接 URL 存储在 YAML 中，其中的 ${NAME} 占位符从环境变量解析。这些信息绝不会出现在日志或模型可见的错误中。
• 输出精简且可预测 — 结果以对象为根节点，采用稳定排序，名称筛选器按字面值进行不区分大小写的匹配，存储过程列表不会展开定义。
• 错误信息可供 Agent 采取行动 — 名称存在歧义时，错误会列出候选架构。错误信息绝不会包含连接详情、凭据、密钥、令牌或行数据。
• 测试攻击场景，而不只是示例 — 通过包含恶意语句的对抗性语料库、基于属性的测试（令牌隔离、防篡改）、针对实际具有写入权限的登录账号进行的实时攻击测试（含前后快照）以及变异测试，检查 SQL 和 PII 边界。结果见 SQL 边界验证。
• 故障可诊断 — 超时或连接错误会附带一个 Reference，stderr 日志会记录同一引用对应的连接阶段、耗时和驱动错误，并移除凭据。请参阅日志记录。

说明

状态： SQL Server 支持所有工具。MySQL 和 MariaDB（engine: mysql 或 mariadb、mysql+pymysql URL）也支持所有工具。由于数据库本身就是目录，因此此处的 schema 始终为 null，而 execute_sql 使用 LIMIT 而非 TOP。请参阅 architecture.md。

快速开始

安装

uvx sql-safe-mcp

或

pip install sql-safe-mcp

需要固定接口时，请锁定版本：uvx sql-safe-mcp==1.5.2。

需要 Python 3.12–3.14、uv（或 pip）；连接 SQL Server 时还需要 Microsoft ODBC Driver 18 for SQL Server。 MySQL 和 MariaDB 使用捆绑的 PyMySQL 驱动，无需其他依赖。

已针对 SQL Server 2022、MySQL 8.4 和 MariaDB 11.4 验证（参见 checks.md）。

Install sql-safe-mcp as a stdio MCP server.
Ask whether to install it for this project/workspace or at user level. Then:
detect and preserve the host's existing MCP config;
configure the server to run via uvx sql-safe-mcp;
create a YAML config template with env placeholders only;
add SQL_SAFE_MCP_CONFIG;
report the env variables the user must set.
Do not store secrets or connection data in tracked files or output. Validate with
sql-safe-mcp --check-config once variables are available.

将 sql-safe-mcp.example-simple.yaml 复制为 sql-safe-mcp.yaml。此最精简配置会公开一个 SQL Server 实例的架构元数据，并且不允许查询行数据。请将完整连接 URL 保存在环境变量中：

version: 1
servers:
  reporting:
    engine: sqlserver
    access_level: metadata
    connection_url: "${REPORTING_SQL_URL}"

这里，reporting 是 Agent 传入的 server 值。变量缺失，或 engine 与 URL 方言不匹配，都会导致 MCP 服务在启动时停止。对于多个服务、本地 PII 规则、共享 PII 规则集、日志记录和运行时限制，请使用配置参考中的注释示例。

检查配置

定义 YAML 文件引用的所有环境变量后，使用 SQL_SAFE_MCP_CONFIG（或 --config）指定该文件，并在不连接任何数据库的情况下检查配置：

SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config

配置会在启动时进行验证，出错时会指出问题，但不会打印 URL 或机密信息。请将凭据保存在主机自己的配置中，切勿提交。服务使用数据库账户的权限，因此请使用专用登录账户，并仅授予任务所需的最低权限。

连接 MCP 客户端

每个客户端配置都需要设置 SQL_SAFE_MCP_CONFIG，以及 YAML 文件引用的环境变量。请将连接 URL 和 PII 密钥保存在 MCP 主机的环境或配置中，切勿放入 YAML 文件或其他受版本控制的文件。

claude mcp add --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-safe -- uvx sql-safe-mcp

{
  "mcpServers": {
    "sql-safe": {
      "command": "uvx",
      "args": ["sql-safe-mcp"],
      "env": {
        "SQL_SAFE_MCP_CONFIG": "/path/to/sql-safe-mcp.yaml",
        "REPORTING_SQL_URL": "mssql+pyodbc://..."
      }
    }
  }
}

codex mcp add sql-safe --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-safe-mcp

PII 安全查询

billing 别名上的 execute_sql 允许执行一条受限的 SELECT。例如，使用以下参数：

{
  "server": "billing",
  "database": "Billing",
  "sql": "SELECT CustomerId, Email FROM dbo.Customers"
}

可以返回类似 [42, "pii:v1:..."] 的行：Agent 可以追踪客户，而无需读取电子邮件地址。令牌只能用于同一服务别名上的 = 和 IN 谓词。如果 FirstName 受到保护，那么 SELECT FirstName FROM Users WHERE FirstName = 'Alice' 会在到达数据库之前被拒绝。只能使用 execute_sql 为同一别名返回的真实 pii:v1:... 令牌筛选受保护的列；仅匹配前缀并不足够。每个令牌都会经过身份验证并绑定到别名，随后进行验证并转换为绑定的数据库值。保护范围涵盖你列出的列，因此请列出所有包含个人数据的列。

文档

• 配置参考 - 别名、连接 URL、PII 规则、运行时限制和日志记录。
• 工具参考 - 参数、响应、错误和支持的 SQL 子集。
• 安全模型 - 信任边界、保障、限制和验证。
• 检查 - 本地、集成和安全验证命令。

安全

MCP 调用方、SQL 输入、数据库元数据、行数据和令牌均不可信。数据库权限仍是主要的授权控制——此服务绝不会扩大这些权限。请阅读完整的安全模型，其中包含限制和验证依据。如需报告漏洞，请通过 SECURITY.md 中的私密渠道提交。

贡献

CONTRIBUTING.md 中介绍了环境设置、检查、测试命令、分支和提交约定，以及发布模式。影响服务运行者的更改会记录在 CHANGELOG.md 中。

License

MIT.