universal-db-mcp

<h1 align="center">universal-db-mcp</h1>

<p align="center">
  <a href="https://github.com/alghanim/universal-db-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/alghanim/universal-db-mcp/ci.yml?branch=main&label=CI"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/alghanim/universal-db-mcp"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/alghanim/universal-db-mcp/badge"></a>
  <a href="LICENSE"><img alt="license: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-4c1"></a>
  <a href="pyproject.toml"><img alt="python: 3.12" src="https://img.shields.io/badge/python-3.12-3776ab"></a>
  <a href="docs/tools.md"><img alt="MCP: 29 tools" src="https://img.shields.io/badge/MCP-29%20tools-6f42c1"></a>
  <a href="#what-it-does"><img alt="databases: 8" src="https://img.shields.io/badge/databases-8-e67e22"></a>
  <a href="#how-it-keeps-the-databases-safe"><img alt="access: read-only" src="https://img.shields.io/badge/access-read--only-0e8a7d"></a>
  <a href="docs/claude-code-integration.md"><img alt="works with: Claude · Cursor · VS Code" src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Cursor%20%C2%B7%20VS%20Code-5b5bd6"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="docs/tools.md">Tools</a> ·
  <a href="docs/security.md">Security model</a> ·
  <a href="#install-offline-air-gapped-sites">Offline install</a> ·
  <a href="#documentation-map">Docs</a> ·
  <a href="https://alghanim.github.io/universal-db-mcp/">Landing page</a> ·
  <a href="SECURITY.md">Report a vulnerability</a>
</p>

**Give AI agents read-only access to your databases, safely.**
universal-db-mcp is an [MCP](https://modelcontextprotocol.io) 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/`):

| Engine | Verified versions |
| --- | --- |
| PostgreSQL | 12, 13, 14, 15, 16, 17 |
| MySQL / MariaDB | MySQL 5.7, 8.0, 8.4; MariaDB 10.6, 11.4 |
| ClickHouse | 23.8, 24.3, 24.8, 25.3 |
| Oracle | 18c, 21c, 23 (thin mode); 11g, 18c, 23 (thick mode, for legacy password verifiers) |
| SQL Server | 2017, 2019, 2022 |
| Db2 | 11.5.8, 11.5.9 |
| SQLite | the CPython build's SQLite |

**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 source

```bash
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

```bash
docker pull ghcr.io/alghanim/universal-db-mcp:0.1.0
gh attestation verify oci://ghcr.io/alghanim/universal-db-mcp:0.1.0 --repo alghanim/universal-db-mcp
```

It is listed in the official [MCP Registry](https://registry.modelcontextprotocol.io)
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

```yaml
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