Lukynnnn/mcp-database-universal

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

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

DATABASE_URL=sqlite:///app.db python -m mcp_database_universal

Run with Docker

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