io.github.Fashad-Ahmed/universal-db-mcp

Universal Database MCP Server

The security-first, Python-native MCP server for database access from AI agents.

---

Why This Exists

Most database MCP servers give AI agents raw SQL access and hope for the best. This server assumes the LLM is untrusted input and applies 8 layers of injection prevention before any query reaches your database — including blocking UNION attacks, stacked statements, time-based injection, and comment bypasses.

Supports: PostgreSQL · SQLite · MySQL · DuckDB (columnar analytics)

---

Zero Setup: Works on Your Laptop Right Now

No Docker. No cloud account. No database server to install. DuckDB and SQLite run in-process:

# Query a local SQLite database — one command, zero infra
SQLITE_PATH=./myapp.db uvx universal-db-mcp

# Query a local DuckDB file or parquet files
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# In-memory DuckDB for throwaway analysis
DUCKDB_PATH=:memory: uvx universal-db-mcp

Add to Claude Code in ~/.claude/mcp_servers.json, or to Claude Desktop in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mydb": {
      "command": "uvx",
      "args": ["universal-db-mcp"],
      "env": {
        "SQLITE_PATH": "/Users/you/projects/myapp/db.sqlite3",
        "ALLOW_DESTRUCTIVE": "false"
      }
    }
  }
}

Restart Claude Desktop / Claude Code after saving — that's it.

That's it. Claude Code discovers the tools automatically.

More client configs (Claude Desktop, Cursor, Windsurf, Docker) in examples/.

---

Security Model: 8 Layers

Read-only by default. Defense-in-depth. Every query validated before it touches the driver.

Layer	What it does
1	Driver-level read-only — PostgreSQL session flag, SQLite mode=ro URI, DuckDB read_only=True. Write rejected before SQL parsing.
2	Keyword blocking — DROP, DELETE, TRUNCATE, ALTER, INSERT, UPDATE, GRANT, EXEC blocked in read-only mode
3	Injection pattern detection — UNION SELECT, stacked statements, SQL comments (--, /*), xp_, SLEEP(), WAITFOR, BENCHMARK()
4	Multiple statement rejection — ; separating statements always blocked
5	Parameter type enforcement — only str, int, float, bool, null accepted as parameters
6	Result size limits — truncated at MAX_RESULT_ROWS (default 1000) to prevent memory exhaustion
7	Identifier sanitization — table/column names stripped of metacharacters in internally-generated SQL
8	DuckDB filesystem blocklist — read_csv(), read_parquet(), glob(), LOAD, INSTALL, httpfs, COPY blocked at adapter level; read_only=True only blocks writes, not file reads

Full threat model: docs/SECURITY.md

---

DuckDB: Analytics Without Infrastructure

DuckDB runs in-process (no server) and reads Parquet, CSV, JSON natively. Connect AI agents to your analytics data without spinning up a warehouse:

# Query parquet files directly
DUCKDB_PATH=:memory: uvx universal-db-mcp

Then in Claude Code:

You: "Load sales.parquet and show me monthly revenue by region"
Claude: [uses query tool → SELECT region, strftime('%Y-%m', date) AS month, SUM(revenue) ...]

---

Natural Language → SQL

No separate NL-to-SQL tool needed — Claude already does this. Give it the schema tool and ask in plain English:

You: "Which customers placed more than 5 orders last month?"
Claude: [calls schema() to see table structure, then query() with the
         generated SQL — every query still passes through all 8 security
         layers before touching your database]

Pair with dry_run: true (DRYRUN=true) while prototyping — Claude gets the query plan back without anything executing.

---

Docker

docker build -t universal-db-mcp .
docker run -i --rm \
  -e POSTGRES_URI=postgresql://readonly:pass@host.docker.internal:5432/mydb \
  -e ALLOW_DESTRUCTIVE=false \
  universal-db-mcp

See examples/docker_mcp_config.json for wiring this into an MCP client.

---

All Databases

# PostgreSQL
POSTGRES_URI=postgresql://readonly:pass@localhost/mydb uvx universal-db-mcp

# SQLite (local file, zero infra)
SQLITE_PATH=./db.sqlite3 uvx universal-db-mcp

# MySQL
MYSQL_URI=mysql://readonly:pass@localhost/mydb uvx universal-db-mcp

# DuckDB (columnar, in-process analytics)
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# Multiple databases simultaneously
POSTGRES_URI=... SQLITE_PATH=... uvx universal-db-mcp

---

MCP Tools

Tool	Description
query	Execute SQL — read-only by default, all 8 security layers apply
schema	Inspect tables and columns — no config needed
explain	Get query execution plan without running the query
health	Check connection status, DB version, and pool metrics
list_databases	Show all configured databases and connection state
query_history	Inspect the last 100 executed queries
snapshot_schema	Capture current schema for drift detection
schema_diff	Compare current schema against the last snapshot

v1.1.0: dry-run mode (DRYRUN=true), table allowlists (WHITELISTED_TABLES), query complexity warnings, structured audit logs, and a --check CLI flag for connectivity validation. See CHANGELOG.md.

---

Configuration

# ── PostgreSQL ─────────────────────────────────────
POSTGRES_URI=postgresql://user:pass@host:5432/db
POSTGRES_READONLY=true          # default: true

# ── SQLite ─────────────────────────────────────────
SQLITE_PATH=/path/to/database.db
SQLITE_READONLY=true            # default: true

# ── MySQL ──────────────────────────────────────────
MYSQL_URI=mysql://user:pass@host:3306/db
MYSQL_READONLY=true             # default: true

# ── DuckDB ─────────────────────────────────────────
DUCKDB_PATH=/path/to/analytics.duckdb   # or :memory:
DUCKDB_READONLY=true            # default: true

# ── Security ───────────────────────────────────────
ALLOW_DESTRUCTIVE=false         # default: false — blocks INSERT/UPDATE/DELETE/DROP
MAX_RESULT_ROWS=1000            # truncate large results
ENABLE_LOGGING=true             # log queries to stderr
QUERY_TIMEOUT=30                # seconds
RATE_LIMIT_RPM=60               # requests per minute

---

Secure Database Users

Always use a dedicated read-only account. Never give the MCP server credentials that can modify data.

PostgreSQL:

CREATE USER mcp_agent WITH PASSWORD 'strong_random_password';
GRANT CONNECT ON DATABASE mydb TO mcp_agent;
GRANT USAGE ON SCHEMA public TO mcp_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_agent;

MySQL:

CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'strong_random_password';
GRANT SELECT ON mydb.* TO 'mcp_agent'@'localhost';
FLUSH PRIVILEGES;

---

Development

git clone <repo-url>
cd universal-db-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (67+ passing, no external DB required for SQLite + DuckDB)
pytest

# Security tests only
pytest tests/test_security.py -v

# With coverage
pytest --cov=src/universal_db_mcp --cov-report=term-missing

---

Architecture

src/universal_db_mcp/
├── server.py          # FastMCP server — 5 tools
├── config.py          # Env-var config via Pydantic
├── adapters/
│   ├── base.py        # Abstract adapter + result dataclasses
│   ├── postgresql.py  # asyncpg, connection pool, read-only via init callback
│   ├── sqlite.py      # aiosqlite, read-only via file URI mode=ro
│   ├── mysql.py       # aiomysql, DictCursor
│   └── duckdb.py      # duckdb, thread-pool executor, lock-guarded
└── security/
    └── sanitizer.py   # SQLSanitizer — 8-layer injection prevention

docs/
└── SECURITY.md        # Full security architecture and threat model

---

vs. Google MCP Toolbox

	This project	Google MCP Toolbox
Runtime	Python — pip install / uvx	Go binary / Docker
Local DBs	SQLite + DuckDB zero-infra	No SQLite
Analytics	DuckDB in-process	No columnar adapter
Auth model	Read-only by default + env vars	IAM / GCP-native
SQL injection	8-layer sanitizer + parameterized	Auth-focused
Extend	Python ecosystem, any pip package	Go plugins
Vendor	Neutral	Google Cloud funnel

Different tools for different jobs. Use this when you want Python-native, local-first, security-hardened access without cloud dependencies.

---

License

MIT — LICENSE

---

Security Notice: This server provides AI agents with database access. Always use read-only credentials, review docs/SECURITY.md before production deployment, and never commit .env files.