Universal Db Mcp

Universal Database MCP Server

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

[CI] [PyPI] [Python 3.10+] [FastMCP] [License: MIT]

[Demo: schema discovery, a real query, a blocked DROP, and dry-run mode]

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 infraSQLITE_PATH=./myapp.db uvx universal-db-mcp
# Query a local DuckDB file or parquet filesDUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp
# In-memory DuckDB for throwaway analysisDUCKDB_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.

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 directlyDUCKDB_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:[email protected]:5432/mydb \  -e ALLOW_DESTRUCTIVE=false \  universal-db-mcp

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

All Databases

# PostgreSQLPOSTGRES_URI=postgresql://readonly:pass@localhost/mydb uvx universal-db-mcp
# SQLite (local file, zero infra)SQLITE_PATH=./db.sqlite3 uvx universal-db-mcp
# MySQLMYSQL_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 simultaneouslyPOSTGRES_URI=... SQLITE_PATH=... uvx universal-db-mcp

MCP Tools

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/dbPOSTGRES_READONLY=true          # default: true
# ── SQLite ─────────────────────────────────────────SQLITE_PATH=/path/to/database.dbSQLITE_READONLY=true            # default: true
# ── MySQL ──────────────────────────────────────────MYSQL_URI=mysql://user:pass@host:3306/dbMYSQL_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/DROPMAX_RESULT_ROWS=1000            # truncate large resultsENABLE_LOGGING=true             # log queries to stderrQUERY_TIMEOUT=30                # secondsRATE_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-mcppython -m venv .venv && source .venv/bin/activatepip install -e ".[dev]"
# Run tests (67+ passing, no external DB required for SQLite + DuckDB)pytest
# Security tests onlypytest tests/test_security.py -v
# With coveragepytest --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

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.