Universal DB (read-only)

universal-db-mcp

Quick start · Tools · Security model · Offline install · Docs · Landing page · Report a vulnerability

Give AI agents read-only access to your databases, safely. universal-db-mcp is an MCP server that lets Claude Code, Cursor, VS Code or any MCP client discover, document, profile, search and query the databases you declare, and nothing else. Every statement is parsed before it runs and must be a single read; it runs on a read-only session, columns that look sensitive are masked, and every call is audited. Writes are refused, not discouraged. The server never calls an LLM, sends no telemetry and installs nothing at runtime, so it also runs on networks with no internet access at all.

Status: hardened through a production security review and three follow-up code reviews (2026-09/10). IMPLEMENTATION_STATUS.md is the honest ledger of what is implemented, what is verified and how, and what is still open; claims here are limited to what its gates and test-evidence/ demonstrate.

What it does

Engines (each version below passes the version matrix, scripts/version_matrix/, results in test-evidence/version-matrix/):

29 tools (docs/tools.md is the contract):

• Connections: db_list_connections, db_test_connection, db_get_capabilities.
• Catalog: db_list_catalogs, db_list_databases, db_list_schemas, db_list_tables, db_get_table, db_list_columns, db_list_views, db_list_synonyms, db_list_routines, db_list_indexes, db_get_relationships, db_get_statistics, db_search_metadata, db_get_catalog.
• Reading data: db_validate_query, db_query, db_sample_table, db_explain (plans, never executions), db_get_query_history.
• Discovery, review and documentation: db_profile_table, db_search_values (find a value across tables and connections without writing SQL), db_infer_relationships, db_review_schema (prioritized optimization findings), db_document_schema (Markdown data dictionary).
• Federated reads: db_federated_query (one statement, or one per connection, merged) and db_federated_join (a bounded hash join across two connections).

How it keeps the databases safe

Defence in depth; details and limitations in docs/security.md and docs/session-safety.md.

1. The database login is the primary control. Give every connection a SELECT-only login limited to the schemas you list in allowed_schemas. The one exception is Db2's db_explain, which writes its plan rows into the explain tables a DBA provisions, reads them back and deletes them: that login also needs INSERT, SELECT and DELETE on those tables, and only there (Oracle's plans go to the session-private PLAN_TABLE, which needs no grant). Column-level grants or views are the real protection for sensitive columns.
2. Read-only sessions. On by default and enforced by the server itself on PostgreSQL, MySQL/MariaDB, ClickHouse and SQLite; Db2 runs at UR and SQL Server at READ UNCOMMITTED, so reads take no share locks. There is no write mode: security.read_only: false, allow_write_operations: true and a connection's read_only: false are rejected when the config loads. Every session is also pinned to the settings that decide how its server lexes a statement (MySQL sql_mode, PostgreSQL standard_conforming_strings, SQL Server QUOTED_IDENTIFIER, ...), so the server reads exactly what the guard parsed.
3. The SQL guard parses every statement in the connection's dialect and accepts one read statement only; anything it cannot parse is refused. Under a non-empty allowed_schemas, every table must be schema-qualified (SELECT * FROM ocean.buoys, not SELECT * FROM buoys), because the engine would otherwise choose the schema. On Oracle, Db2 and PostgreSQL, CTE names and unquoted table names must be ASCII. Views that show other sessions' SQL, column statistics or stored credentials are refused whatever allowed_system_schemas opens; Oracle's SYS.DUAL and Db2's SYSIBM.SYSDUMMY1 to SYSDUMMY4 are always readable. Bound parameters reach the driver exactly as validated.
4. Masking that refuses what it cannot prove. Columns matching the sensitive patterns (built in, plus security.mask_columns) are masked by where each output value comes from. A statement over a table with masked columns is accepted only in shapes the analysis fully proves (columns, expressions, aggregates, window functions, joins, CTEs, subqueries, unions, * over listed tables); anything else is refused before it runs, with the construct named. Predicates are not masked: a WHERE on a masked column can still narrow results.
5. Bounded, sanitized, audited. Row, byte, cell and time ceilings; a per-query memory cap on ClickHouse (2 GiB by default, options.max_memory_usage); size caps checked before any parsing; driver error text sanitized. Every call is audited, by default to the platform's state directory (/var/log/universal-db-mcp/audit.jsonl for the service's config, %ProgramData%\UniversalDB MCP\logs\audit.jsonl on Windows, ~/.universal-db-mcp/audit.jsonl for a per-user config).
6. stdio is not a security boundary. A stdio registration runs the server as your user inside the agent, so an agent that can run shell commands or read files can read the credentials in ~/.universal-db-mcp/secrets/ and connect directly, outside the guard. Use SELECT-only logins, or run the server in HTTP mode (bearer token, behind your reverse proxy) under a separate service account.

Quick start

From PyPI

uv tool install 'udbmcp[all]'   # or: pipx install 'udbmcp[all]'

udbmcp add-connection # writes ~/.universal-db-mcp/config.yaml, secrets in private files beside it udbmcp configure-agents # registers it with Claude Code, Claude Desktop, Cursor, VS Code, Cline

[all] brings the PostgreSQL, MySQL/MariaDB, ClickHouse and Oracle (thin mode) drivers; SQLite needs none. SQL Server (udbmcp[mssql]) and Db2 (udbmcp[db2]) also need their vendors' client libraries. The wheel on PyPI is the one the release's signed bundle carries, uploaded with PEP 740 attestations. Run configure-agents from an install like this one, not through uvx: uvx runs from a cache that uv prunes, and configure-agents refuses to register an interpreter there.

From source

uv venv --python 3.12 .venv

uv pip install --python .venv/bin/python -e '.[dev]' .venv/bin/python examples/sqlite-demo/create_demo.py # synthetic fixture UDBMCP_CONFIG=examples/sqlite-demo/config.yaml .venv/bin/python -m universal_db_mcp serve --transport stdio

Register the server with your agents with .venv/bin/udbmcp configure-agents (Claude Code, Claude Desktop, Cursor, VS Code, Cline and others; docs/claude-code-integration.md). It writes the launch command with python -I (isolated mode), so the package and its dependencies must be installed in a virtual environment, as above; pip install --user or PYTHONPATH-only setups are refused. It registers the system config (/etc/universal-db-mcp/config.yaml, on Windows %ProgramData%\UniversalDB MCP\config.yaml) when your user can read it, otherwise the per-user ~/.universal-db-mcp/config.yaml; export an absolute UDBMCP_CONFIG first to choose another. The .deb ships the system config readable by every user, so on a .deb host make it root:udbmcp 0640 first (docs/claude-code-integration.md).

udbmcp add-connection adds a connection interactively and stores its secrets with private permissions; udbmcp doctor checks a config, its secrets and (with --connectivity) every database.

With the container image

docker pull ghcr.io/alghanim/universal-db-mcp:0.2.0

gh attestation verify oci://ghcr.io/alghanim/universal-db-mcp:0.2.0 --repo alghanim/universal-db-mcp

It is listed in the official MCP Registry as io.github.alghanim/universal-db-mcp, so clients that browse the registry can install it. Mount your config and its secrets read-only and run it over stdio or HTTP as docs/offline-deployment.md (Container mode) describes. The image has no SQL Server driver; the same section shows how to add Microsoft's.

A minimal connection

connections:

sales: type: postgres host: pg.example.internal port: 5432 database: sales username_file: /etc/universal-db-mcp/secrets/sales.user # 0600, owned by the service account password_file: /etc/universal-db-mcp/secrets/sales.pw allowed_schemas: [reporting] tls: enabled: true ca_file: /etc/universal-db-mcp/ca/internal-ca.pem

config.example.yaml documents every setting, per engine.

Install offline (air-gapped sites)

See docs/offline-deployment.md, and docs/site-upgrade-runbook.md for a site that installs from a release stick (scripts/package/release_usb.sh builds one). Short version:

# staging machine (authori