safedb-mcp

SafeDB MCP

SafeDB MCP 是一款安全的 Model Context Protocol 服务，可让 AI Agent 在严格的只读防护措施下检查和查询 Postgres、MySQL、MariaDB 和 SQLite。它面向希望提供实用数据库访问能力、又不想向 Agent 交出不受限制的生产环境凭据的团队。

直接向 Agent 提供数据库凭据很危险，因为一次错误的提示词、工具调用或生成的 SQL 语句，就可能修改数据、泄露敏感列，或执行开销巨大的查询。SafeDB MCP 在 Agent 与数据库之间加入策略层：仅开放配置的架构和表；执行前解析并验证 SQL；限制行数；对结果进行脱敏；并审计每次查询尝试。

本项目处于 MVP 阶段。它宁可误报并阻止查询，也不允许不安全的访问；它不宣称 SQL 安全性绝对可靠。

功能

• MCP 工具：list_schemas、list_tables、describe_table、run_readonly_query、explain_query、get_safedb_policy
• 通过 pg 支持 Postgres
• 通过 mysql2 支持 MySQL 和 MariaDB
• 通过 sql.js 支持 SQLite 文件
• 支持带环境变量展开的 YAML 或 JSON 配置
• 基于 AST 的只读 SQL 防护，支持 SELECT、WITH ... SELECT、UNION 和 EXPLAIN SELECT
• 可通过联接、CTE、嵌套子查询、别名和联合查询检测表
• 列投影检查会阻止通过别名或表达式选取受屏蔽字段
• 可配置表允许列表、拒绝列表、行数限制和语句超时
• PII 脱敏方式：redact、email、partial 和确定性 hash
• JSONL 审计日志，不包含原始结果数据
• CLI 可执行文件：safedb-mcp
• TypeScript、Vitest、ESLint、Prettier

快速入门

npx @safedb/safedb-mcp init --output safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp validate-config --config safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp test-connection --config safedb.yaml
DATABASE_URL=postgres://readonly:password@localhost:5432/app npx @safedb/safedb-mcp --config safedb.yaml

请使用具有只读权限的专用数据库角色。SafeDB MCP 是纵深防御层，不能取代遵循最小权限原则的数据库凭据。

Docker

Docker 镜像将 SafeDB MCP 与 Node.js 及其生产依赖打包在一起，可在任何安装了 Docker 的主机上以相同方式运行。

在本地构建镜像：

docker build -t safedb-mcp .

挂载配置文件并运行 MCP 服务：

docker run --rm -i \
  -e DATABASE_URL=postgres://readonly:[email protected]:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp

在镜像名称后传入 CLI 命令：

docker run --rm \
  -e DATABASE_URL=postgres://readonly:[email protected]:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp --config /config/safedb.yaml validate-config

配置示例

database:
  type: postgres
  url: ${DATABASE_URL}

safety:
  default_limit: 100
  max_limit: 1000
  statement_timeout_ms: 5000
  allow_explain: true

access:
  schemas:
    public:
      allow_tables:
        - users
        - orders
        - products
      deny_tables:
        - secrets
      column_masks:
        users.email: email
        users.phone: partial
        users.password_hash: redact
        users.ssn: redact

audit:
  path: safedb-audit.jsonl

对于 MySQL 或 MariaDB，请设置 database.type，并将数据库名称用作访问架构：

database:
  type: mysql
  url: ${DATABASE_URL}

access:
  schemas:
    app:
      allow_tables:
        - users
        - orders
      deny_tables:
        - secrets

对于 SQLite，请将 database.type 设置为 sqlite，将 database.path 指向 .db 文件，并使用 main 作为访问架构：

database:
  type: sqlite
  path: ./app.db

access:
  schemas:
    main:
      allow_tables:
        - users
        - orders
      deny_tables:
        - secrets

MCP 客户端配置

Claude Desktop：

{
  "mcpServers": {
    "safedb": {
      "command": "safedb-mcp",
      "args": ["--config", "/absolute/path/to/safedb.yaml"],
      "env": {
        "DATABASE_URL": "postgres://readonly:password@localhost:5432/app"
      }
    }
  }
}

Cursor 或 Hermes 风格的 MCP 配置：

{
  "servers": {
    "safedb": {
      "command": "safedb-mcp",
      "args": ["--config", "/absolute/path/to/safedb.yaml"],
      "env": {
        "DATABASE_URL": "postgres://readonly:password@localhost:5432/app"
      }
    }
  }
}

安全保证

SafeDB MCP 致力于确保：

• 只能通过 MCP 工具检查或查询配置的架构和表。
• 执行前会解析 SQL，并阻止修改数据的语句类型或多条语句。
• 根据联接、CTE、嵌套子查询、别名和联合查询中发现的实际表检查表访问策略。
• 无法通过别名或表达式选取会绕过响应脱敏的受屏蔽列。
• 查询会在只读事务中执行，并在驱动支持的情况下设置本地语句超时。
• 返回的行数会受到外层 LIMIT 限制。
• 在返回工具响应前，会对配置的 PII 字段进行脱敏。
• 审计日志会记录尝试、决策、检测到的表、行数和耗时，但不会记录原始结果行。
• 不会有意记录密码和密钥。

非目标

• 对查询安全性的形式化证明。
• 支持每种有效方言特有的只读 SQL 结构。
• 写操作、迁移、存储过程执行或 COPY。

开发

npm install
npm run build
npm test
npm run lint

路线图

• 按工具和表设置速率限制。
• 可选的 OpenTelemetry 跟踪。
• 签名审计日志。
• 发布 Docker 镜像和 Helm chart。

许可证

MIT