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 分