pii-safe-db-mcp

An MCP server that lets an LLM query MySQL or PostgreSQL while masking PII before any value leaves your machine. It also controls how sensitive columns may be used in a query.

Most database MCP servers forward the raw result set straight to the model. This one sits in between:

LLM  ──►  pii-safe-db-mcp  ──────────────────────────────────►  MySQL / Postgres
              │
              ├─ 1. static read-only guard (single statement, no writes/files/sleep)
              ├─ 2. SQL AST policy check
              │      • table allow / deny list (joins, subqueries, CTEs too)
              │      • sensitive columns in WHERE / JOIN / GROUP BY / ORDER BY
              │      • taint tracking through aliases, CTEs, derived tables, expressions
              ├─ 3. execution in a READ ONLY transaction + timeout
              ├─ 4. result masking (column origin + AST taint + value scanning)
              ├─ 5. error-message scrubbing
              └─ 6. audit log (no raw PII, ever)

Why masking the output isn't enough

SELECT c.customer_id, c.name
FROM customers c JOIN loans l ON c.pan = l.pan
WHERE c.customer_id = 123;

Every value this query returns can be masked, yet it still uses the customer's PAN to link two datasets. Filters work the same way. WHERE email LIKE 'a%', ORDER BY name and CASE WHEN pan = 'X' act as oracles: they let a model reconstruct values one character at a time without ever seeing them. pii-safe-db-mcp parses every query into an AST and rejects these uses according to your policy.

Related MCP server: @guardbee/mcp-db-gateway

Features

• MySQL and PostgreSQL in one server

• Read-only, enforced three ways: a static SQL guard, a READ ONLY transaction, and a statement timeout

• SQL AST security (v0.2): per-table rules for sensitive columns in WHERE/HAVING, JOIN ON/USING, GROUP BY/PARTITION BY and ORDER BY, including positional (ORDER BY 1) and alias references

• Taint tracking (v0.2): sensitive columns are followed through aliases, CTEs, derived tables, scalar subqueries, UNIONs and functions. UPPER(name) AS x and SUBSTR(pan, 1, 3) are still masked.

• Table allowlist and denylist (v0.2): enforced for every table a query touches, including joins, subqueries and CTEs, and also applied to list_tables, describe_table, pii_scan, DESCRIBE and SHOW

• Fail-closed (v0.2): when a policy is configured, any query that can't be parsed and verified is rejected

• Error sanitisation (v0.2): database errors that echo values (Duplicate entry 'Ravi Kumar'…, Key (email)=(…)) are scrubbed

• Audit logging (v0.2): each record holds actor, environment, database, operation, decision, duration, row count, PII count and a literal-free query fingerprint. It never contains raw PII.

• Indian PII recognisers (v0.2): PAN, Aadhaar (Verhoeff-checked), GSTIN, IFSC, UPI IDs, bank account numbers (context-anchored) and mobile numbers, plus custom patterns such as loan IDs

• Alias-proof column detection: SELECT email AS x is still masked, because the server uses the driver's column-origin metadata and the AST

• Value scanning: PII hidden in notes, comments or JSON columns is masked inline

• LLM-friendly tokens: the same value always maps to the same token (<EMAIL_75423bc6b9>), so the model can still join on output, count distinct and compare

• Secrets are never oracles: password, token, OTP and API-key columns can't be filtered, joined, grouped or sorted on, even without a policy file

Tools

Quick start

Claude Desktop / Claude Code

{
  "mcpServers": {
    "safe-db": {
      "command": "npx",
      "args": ["-y", "pii-safe-db-mcp"],
      "env": {
        "DATABASE_URL": "postgres://readonly_user:pass@localhost:5432/customer_db",
        "PII_POLICY_FILE": "/path/to/pii-policy.json",
        "AUDIT_LOG": "/var/log/pii-safe-db-mcp/audit.jsonl",
        "AUDIT_ENVIRONMENT": "preprod"
      }
    }
  }
}

Claude Code one-liner:

claude mcp add safe-db \
  -e DATABASE_URL=mysql://readonly:pass@localhost:3306/customer_db \
  -e PII_POLICY_FILE=$PWD/pii-policy.json \
  -- npx -y pii-safe-db-mcp

Policy file

The policy file is optional. Without one, the server behaves as v0.1 did: masking only, except that secret columns are never usable as oracles. See examples/pii-policy.json for a complete example.

{
  "allowed_tables": ["customers", "loans", "public.payments"],
  "denied_tables": ["internal_audit"],
  "default": {
    "allow_filtering": true,
    "allow_joining": true,
    "allow_grouping": true,
    "allow_sorting": true
  },
  "tables": {
    "customers": {
      "sensitive_columns": ["name", "mobile", "pan", "aadhaar", "email"],
      "blocked_columns": ["kyc_document_url"],
      "allow_filtering": false,
      "allow_joining": false,
      "allow_grouping": false,
      "allow_sorting": false
    },
    "loans": {
      "sensitive_columns": ["pan"],
      "allow_joining": false
    }
  },
  "custom_patterns": [
    { "name": "LOAN_ID", "pattern": "\\bLN\\d{8}\\b", "column_names": ["loan_no"] }
  ],
  "fail_closed": true,
  "treat_detected_pii_as_sensitive": true
}

Always allowed: COUNT(col) and COUNT(DISTINCT col) on sensitive columns, because they reveal no values.

Always force-masked: any output expression derived from a sensitive column. If a sensitive expression is combined with SELECT *, it must have an alias.

Audit log

By default, one JSON line per tool call is written to stderr. Set AUDIT_LOG to a file path to append to a file (mode 600), or to off to disable it.

{
  "timestamp": "2026-11-07T09:23:57.249Z",
  "actor": "claude-code",
  "environment": "preprod",
  "database": "customer_db",
  "db_type": "mysql",
  "tool": "query",
  "operation": "SELECT",
  "decision": "ALLOWED",
  "tables": ["customers", "loans"],
  "duration_ms": 12,
  "rows_returned": 10,
  "pii_detected": 3,
  "masked_columns": ["name", "mobile"],
  "query_fingerprint": "ef4144c6cfcee85f",
  "query_shape": "SELECT name, mobile FROM customers WHERE id = ?",
  "raw_pii_logged": false
}

• decision is ALLOWED, BLOCKED (policy or guard) or ERROR (database error, sanitised).

• actor comes from AUDIT_ACTOR. If that isn't set, the MCP client's own name is used (e.g. claude-code).

• query_shape has every literal replaced by ?, so it never contains values. Disable it with AUDIT_QUERY_SHAPE=false. Bind parameters are never logged.

Configuration

Examples

-- ✅ allowed, output masked
SELECT c.id, UPPER(c.full_name) AS nm, l.amount
FROM customers c JOIN loans l ON c.id = l.customer_id ORDER BY l.amount DESC
-- → [{"id":1,"nm":"<NAME_ac0d9937c4>","amount":500000}, ...]

-- ✅ aggregates over sensitive columns
SELECT city, COUNT(DISTINCT email) AS n FROM customers GROUP BY city

-- ❌ Blocked: Column customers.pan is sensitive and cannot be used in JOIN conditions
SELECT c.name FROM customers c JOIN loans l ON c.pan = l.pan

-- ❌ Blocked: Column customers.email ... cannot be used in WHERE/HAVING filters or comparisons
SELECT id FROM customers WHERE email LIKE 'r%'

-- ❌ Blocked: Access to table "salaries" is not allowed by policy.
SELECT * FROM customers c WHERE EXISTS (SELECT 1 FROM salaries s WHERE s.id = c.id)

Detected PII

Detected by column name (snake_case and camelCase):

Detected by value: emails, UPI IDs, phone numbers (international and Indian mobile), credit cards (Luhn-checked), Aadhaar (Verhoeff-checked), PAN, GSTIN, IFSC, bank accounts next to an "A/C No" or "account" label, US SSN, IPv4, and your custom patterns.

Security notes and limitations

• Use a read-only database user. The SQL guard, AST policy and read-only transaction are defence in depth. They are not a replacement for least privilege. For the strongest guarantee, also expose only a curated schema or views to that user.

• Name detection and value patterns are heuristics. Run pii_scan, then list any extra columns under tables.<t>.sensitive_columns.

• Value scanning can't detect free-text names or addresses. Add those columns to the policy.

• Configure a policy for strict guarantees. With a policy, the server fails closed on SQL it can't parse. Without one, unparseable SQL falls back to masking only.

• JSON paths are covered by value scanning, not the AST. In data->>'pan', the output is masked by the PAN pattern. If a whole JSON column is sensitive, list it in sensitive_columns.

Development

npm install
npm test        # builds, then runs unit, SQL-bypass and end-to-end regression tests
npm start       # runs the server on stdio (needs DATABASE_URL)

The test suites:

License

MIT © Aqib Siddiqui