Safedb Mcp

io.github.narekmalk由 GitHub 账号 narekmalk 发布v0.5.0更新于 Oct 24, 2026

A secure MCP server that lets AI agents query databases safely.

已验证STDIO仅桌面数据库安全与监控

概览

AI 生成的概览

本地 MCP 服务器,让 AI 助手在策略层、脱敏与审计日志的约束下,对 Postgres、MySQL、MariaDB 和 SQLite 进行只读查询与结构查看。

可以做什么
  • 列出允许范围内的 schema、数据表与表结构
  • 执行只读的 SELECT、CTE、UNION 与 EXPLAIN 查询,并受行数上限和超时限制
  • 查看当前生效的安全策略,包括限制、允许的表与列脱敏规则
  • 对配置的列应用 redact、email、partial、hash 等脱敏处理
  • 将每次查询尝试写入 JSONL 审计日志,不记录原始结果行
适用场景
适合希望让助手探索或回答关系型数据库问题、但不想交出无限制凭据的场景,前提是你能明确划定可访问的 schema、表和列。
运行要求
以本地 npm 包(npx @safedb/safedb-mcp)或 Docker 镜像运行,使用 npm 包时需要 Node.js。需要 YAML 或 JSON 配置文件,以及通过 DATABASE_URL 等环境变量提供的数据库连接地址或 SQLite 文件路径。建议使用专用的只读数据库角色。
安装前请注意
项目自称为 MVP,并不声称具备完美的 SQL 安全性。它需要以环境变量提供数据库凭据,应使用最小权限的只读角色而非生产写权限账号。查询仍会到达你的数据库,审计日志会记录尝试、识别到的表与行数。脱敏与白名单效果取决于配置是否正确。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Safedb Mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

SafeDB MCP

[CI] [npm version] [safedb-mcp MCP server]

SafeDB MCP is a secure Model Context Protocol server that lets AI agents inspect and query Postgres, MySQL, MariaDB, and SQLite with strict read-only guardrails. It is designed for teams that want useful database access without handing an agent unrestricted production credentials.

Direct database credentials are dangerous for agents because a single bad prompt, tool call, or generated SQL statement can mutate data, exfiltrate sensitive columns, or run expensive queries. SafeDB MCP puts a policy layer between the agent and your database: only configured schemas and tables are visible, SQL is parsed and validated before execution, row counts are capped, results are masked, and every query attempt is audited.

This project is an MVP. It prefers false positives and blocked queries over unsafe access, and it does not claim perfect SQL security.

Features

  • MCP tools: list_schemas, list_tables, describe_table, run_readonly_query, explain_query, get_safedb_policy
  • Postgres support through pg
  • MySQL and MariaDB support through mysql2
  • SQLite file support through sql.js
  • YAML or JSON config with environment expansion
  • AST-backed read-only SQL guardrails for SELECT, WITH ... SELECT, UNION, and EXPLAIN SELECT
  • Table detection through joins, CTEs, nested subqueries, aliases, and unions
  • Column projection checks that block masked fields selected through aliases or expressions
  • Configurable table allowlists, denylists, row limits, and statement timeout
  • PII masking: redact, email, partial, and deterministic hash
  • JSONL audit log with no raw result data
  • CLI binary: safedb-mcp
  • TypeScript, Vitest, ESLint, Prettier

Quickstart

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

Use a dedicated database role with read-only permissions. SafeDB MCP is a defense-in-depth layer, not a replacement for least-privilege database credentials.

Docker

A Docker image packages SafeDB MCP with Node.js and its production dependencies so it can run the same way on any host with Docker.

Build the image locally:

bash
docker build -t safedb-mcp .

Run the MCP server with a mounted config file:

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

Pass CLI commands after the image name:

bash
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

Example Config

yaml
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

For MySQL or MariaDB, set database.type and use the database name as the access schema:

yaml
database:  type: mysql  url: ${DATABASE_URL}
access:  schemas:    app:      allow_tables:        - users        - orders      deny_tables:        - secrets

For SQLite, set database.type to sqlite, point database.path at the .db file, and use main as the access schema:

yaml
database:  type: sqlite  path: ./app.db
access:  schemas:    main:      allow_tables:        - users        - orders      deny_tables:        - secrets

MCP Client Config

Claude Desktop:

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

Cursor or Hermes-style MCP config:

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

Security Guarantees

SafeDB MCP aims to guarantee that:

  • Only configured schemas and tables are inspectable or queryable through the MCP tools.
  • SQL is parsed before execution, and mutating statement types or multiple statements are blocked.
  • Table access policy is checked against real tables found through joins, CTEs, nested subqueries, aliases, and unions.
  • Masked columns cannot be selected through aliases or expressions that would bypass response masking.
  • Query execution happens inside a read-only transaction with a local statement timeout where the driver supports it.
  • Returned rows are capped by an outer LIMIT.
  • Configured PII fields are masked before tool responses are returned.
  • Audit logs record attempts, decisions, detected tables, row counts, and duration without logging raw result rows.
  • Passwords and secrets are not intentionally logged.

Non-Goals

  • Formal proof of query safety.
  • Support for every valid dialect-specific read-only SQL construct.
  • Write operations, migrations, stored procedure execution, or COPY.

Development

bash
npm installnpm run buildnpm testnpm run lint

Roadmap

  • Per-tool and per-table rate limits.
  • Optional OpenTelemetry traces.
  • Signed audit logs.
  • Published Docker image and Helm chart.

License

MIT

来源:README.md,提交 dab5ab0

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.5.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分