File size: 3,448 Bytes
72334df 9e01acf 72334df 9e01acf 72334df 7947ce0 72334df 9e01acf 7947ce0 72334df 7947ce0 9e01acf 72334df 9e01acf 72334df 34abc80 72334df 917cf21 34abc80 9e01acf 72334df 9e01acf 34abc80 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | ---
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 |