sql-guard-mcp

A read-only SQL Model Context Protocol server that you can safely point an AI agent at.

Giving an agent database access is useful and risky. Agents write SELECT * on tables with personal data, run unbounded queries, and sometimes produce a DELETE. This server lets an agent explore and query SQLite or PostgreSQL, but every query passes three independent layers first, and each one would stop the bad case on its own.

flowchart LR
    A[AI agent] -- run_query --> G
    subgraph L1 [Layer 1 · AST guard]
      G[sqlglot parse] --> C1{one statement?<br/>SELECT only?<br/>no INTO / FOR UPDATE?}
      C1 --> C2{tables allowed?<br/>columns visible?<br/>functions allowed?}
      C2 --> RW[rewrite: clamp LIMIT<br/>to max_rows + 1]
    end
    subgraph L2 [Layer 2 · read-only connection]
      RW --> RO[SQLite mode=ro + query_only<br/>Postgres READ ONLY txn, always rolled back]
    end
    subgraph L3 [Layer 3 · time box]
      RO --> TO[SQLite progress-handler deadline<br/>Postgres statement_timeout]
    end
    TO --> R[rows + truncated flag]
    C1 -. reason .-> A
    C2 -. reason .-> A
    G & TO --> AU[(audit.jsonl)]

Tools

Rejections are written for the agent to act on. For example, SELECT * on 'customers' would expose restricted columns (email); list the columns you need gives the model a way forward instead of a dead end.

Related MCP server: PgSafe MCP

What gets blocked

The test suite bypasses the guard on purpose and hands raw DELETE statements and pg_sleep straight to the executor. That proves layers two and three hold on their own and aren't just backing up the parser.

Quick start

git clone https://github.com/geethapriya1625/sql-guard-mcp && cd sql-guard-mcp
pip install -e ".[dev]"
python examples/make_demo_db.py          # small shop database
sql-guard-mcp --config examples/policy.yaml

Claude Desktop / any MCP client

{
  "mcpServers": {
    "shop-db": {
      "command": "sql-guard-mcp",
      "args": ["--config", "/absolute/path/to/policy.yaml"]
    }
  }
}

For remote clients, run --transport streamable-http.

Policy

database_url: postgresql://readonly_user:${PGPASSWORD}@db.internal/shop   # env vars expand
max_rows: 50
timeout_ms: 2000
allowed_tables: []            # empty = all, minus denied_tables
denied_tables: [api_keys]
denied_columns: [customers.email]
audit_log: audit.jsonl

In production, also connect as a database role that only has SELECT grants. This server is defense in depth on top of least privilege, not a replacement for it.

A real session

Captured from the stdio transport against the demo database:

tools: ['list_tables', 'describe_table', 'run_query', 'explain_query']

run_query: revenue by customer, excluding cancelled orders (4-table join)
→ {"columns": ["name", "revenue"], "rows": [["Globex Corporation", 2881.5], ["Initech LLC", 2400.0],
   ["Contoso GmbH", 1242.0], ["Northwind Traders", 1130.0], ["Umbrella Logistics", 649.95]],
   "row_count": 5, "truncated": false, "elapsed_ms": 1.05}

run_query: SELECT * FROM customers
→ {"error": "SELECT * on 'customers' would expose restricted columns (email); list the columns you need"}

run_query: SELECT secret FROM api_keys
→ {"error": "table 'api_keys' is not available to this agent"}

run_query: DELETE FROM orders
→ {"error": "only SELECT queries are allowed, got DELETE"}

Each call writes an audit line with the original SQL, the SQL that actually ran (with the injected LIMIT 51), the decision, row count, timing and the tables touched.

Design decisions

• Parse, don't pattern-match. Regex filters miss DeLeTe, comments, and data-modifying CTEs. sqlglot gives a typed AST in the right dialect, so the checks walk real nodes.

• Fail closed on the unknown. Anything sqlglot can only parse as a generic Command is rejected, so statements the parser doesn't model are blocked by default.

• Fetch max_rows + 1. That's the cheapest way to tell the agent its result was cut off without running a COUNT(*).

• Hide instead of erroring in describe_table. The agent never learns restricted column names, but it does learn that some exist, so it isn't confused when SELECT * is refused.

• Conservative column checks. An unqualified column that shares a name with a restricted one is refused in any query that touches the restricted table. Occasionally that's a false positive, but it never leaks data.

Tests

pytest                                                             # SQLite: 51 tests
TEST_POSTGRES_URL=postgresql://user:pass@localhost/db pytest       # + 5 Postgres tests

56 tests cover 27 rejection cases (injection, writes, hidden columns, system catalogs, dangerous functions), the row cap, truncation, the read-only connection with the guard bypassed, runaway-query timeouts, introspection, the audit log, and full MCP round trips through the SDK client. CI runs everything on Python 3.11 to 3.13 against a Postgres 16 service container.

License

MIT