SafeDB MCP

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

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

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:

docker build -t safedb-mcp .

Run the MCP server with a mounted config file:

docker run --rm -i \
  -e DATABASE_URL=postgres://readonly:password@host.docker.internal:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp

Pass CLI commands after the image name:

docker run --rm \
  -e DATABASE_URL=postgres://readonly:password@host.docker.internal:5432/app \
  -v "$PWD/safedb.yaml:/config/safedb.yaml:ro" \
  safedb-mcp --config /config/safedb.yaml validate-config

Example 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

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

database:
  type: 

... [View full README on GitHub](https://github.com/narekmalk/safedb-mcp#readme)