| --- |
| language: |
| - en |
| tags: |
| - mcp |
| - model-context-protocol |
| - ai-tools |
| - database |
| - sqlite |
| - postgresql |
| - mysql |
| - mssql |
| library_name: mcp-database-universal |
| license: mit |
| --- |
| |
| # MCP Database Universal |
|
|
| A reasoning interface for databases — not a thin execution wrapper. Designed so LLM agents understand *what* the data means, not just how to fetch it. |
|
|
| ## What it does |
|
|
| - **7 tools** designed for agent thinking: `test_connection`, `list_tables`, `inspect_table`, `query`, `natural_query`, `profile_database`, `schema_graph` |
| - **4 database engines**: SQLite (built-in), PostgreSQL, MySQL, MSSQL (optional extras) |
| - **Read-only by default** — write operations only with `DATABASE_WRITE_ENABLED=true` |
| - **Safety layer** — SQL injection detection, read-only classification, LIMIT enforcement, query timeout, row limits |
| - **LLM formatter** — type translation (e.g. `VARCHAR(255)` → "text, max 255 chars"), NULL → `(empty)`, output size cap |
| - **Schema inspector** — relationship discovery + Mermaid ER diagram generation |
| - **Zero-config SQLite** via `DATABASE_URL=sqlite:///path/to.db` |
|
|
| ## Installation |
|
|
| ```bash |
| pip install mcp-database-universal |
| pip install "mcp-database-universal[postgres]" # PostgreSQL support |
| pip install "mcp-database-universal[mysql]" # MySQL support |
| pip install "mcp-database-universal[mssql]" # MSSQL support |
| ``` |
|
|
| ## Quick Start |
|
|
| ### Run locally |
|
|
| ```bash |
| DATABASE_URL=sqlite:///app.db python -m mcp_database_universal |
| ``` |
|
|
| ### Run with Docker |
|
|
| ```bash |
| docker run -i -e DATABASE_URL=sqlite:////data/app.db \ |
| -v ./data:/data mcp-database-universal:latest |
| ``` |
|
|
| ## Configuration (env vars) |
|
|
| | Variable | Description | Default | |
| |---------------------------|---------------------------------------------------------|------------| |
| | `DATABASE_URL` | `sqlite:///path.db`, `postgresql://...`, `mysql://...`, `mssql://...` | required | |
| | `DATABASE_READ_ONLY` | Enforce read-only mode | `true` | |
| | `DATABASE_WRITE_ENABLED` | Allow write operations (INSERT/UPDATE/DELETE) | `false` | |
| | `DATABASE_MAX_ROWS` | Max rows returned per query | `1000` | |
| | `DATABASE_MAX_QUERY_TIME` | Query timeout in seconds | `30` | |
| | `DATABASE_MAX_OUTPUT_BYTES` | Cap on result payload size | `50000` | |
| | `OPENAI_API_KEY` | API key for the LLM-backed `natural_query` (OpenAI) | — | |
| | `ANTHROPIC_API_KEY` | API key for the LLM-backed `natural_query` (Anthropic) | — | |
|
|
| ## Tools |
|
|
| | Tool | Description | |
| |--------------------|----------------------------------------------------------| |
| | `test_connection` | Verify connection, get engine type, version, size | |
| | `list_tables` | Overview of tables with row counts and relationships | |
| | `inspect_table` | Full table structure: columns, types, keys, sample data | |
| | `query` | Execute parametrized, safety-checked SQL | |
| | `natural_query` | Ask in plain language, get SQL + results + explanation | |
| | `profile_database` | Value distributions, NULL rates, relationships, sizes | |
| | `schema_graph` | Mermaid ER diagram of relationships | |
|
|
| ## License |
|
|
| MIT |
