MCP Database Server

A reasoning interface for databases for MCP-capable AI agents — not a thin SQL wrapper.

mcp-database-universal gives AI agents a set of 7 reasoning tools to explore and query a database safely, understand its schema and data shape, run natural-language questions, and visualize relationships — all without exposing raw connection internals.

Features

• 7 reasoning tools designed for AI agents: test connection, list tables, inspect a table, run parameterized SQL, ask questions in plain language, profile data, and render an ER diagram.
• Multi-engine: SQLite (built-in) plus optional PostgreSQL, MySQL, and MSSQL.
• Safety first: read-only by default, parameterized queries, statement validation, row/time/output limits.
• LLM-friendly output: types translated, NULLs handled, results formatted in Markdown tables with context.
• Schema introspection: auto-discover tables, columns, indexes, foreign keys, and relationships.
• Natural language queries: translate plain-text questions into SQL and return results.

Supported engines

Install

pip install mcp-database-universal

# With optional engines:
pip install "mcp-database-universal[postgres]"
pip install "mcp-database-universal[mysql]"
pip install "mcp-database-universal[mssql]"
# or everything:
pip install "mcp-database-universal[all]"

Quick start

Run the server over STDIO (the default transport for MCP clients):

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

Connection URLs:

sqlite:///path/to/db.db              SQLite (file)
sqlite:///:memory:                   SQLite (in-memory)
postgresql://user:pass@host:5432/db  PostgreSQL
mysql://user:pass@host:3306/db       MySQL
mssql://user:pass@host:1433/db       MSSQL (uses ODBC Driver 18)

Docker

docker build -t mcp-db .

# Mount a SQLite database read-only:
docker run --rm -i \
  -v /host/path/app.db:/data/app.db:ro \
  -e DATABASE_URL=sqlite:////data/app.db \
  mcp-db

# Or in-memory:
docker run --rm -i -e DATABASE_URL=sqlite:///:memory: mcp-db

Configuration

All configuration is done through environment variables.

Tools

Example: query with parameters

{
  "sql": "SELECT * FROM users WHERE id = :id AND active = :active",
  "params": "{\"id\": 42, \"active\": true}"
}

Parameters use :name placeholders; pass the values as a JSON string in params.

Example: natural_query

question: "How many users are there?"
-> SELECT COUNT(*) FROM users
question: "Show me all orders"
-> SELECT * FROM orders LIMIT 100

A working example against a small sample database is in examples/ together with ready-to-use configuration snippets for common MCP clients.

MCP client configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "mcp_database_universal"],
      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
    }
  }
}

Cursor / other CLI-based clients

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mcp-database-universal"],
      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
    }
  }
}

Windows note: the async Postgres driver requires the Windows selector event loop. The package sets this policy automatically on win32, so no extra configuration is needed.

Development

pip install -e ".[dev]"
pytest

Integration tests for PostgreSQL/MySQL use Docker Compose and are skipped automatically if the servers are unreachable:

docker compose -f tests/integration/docker-compose.yml up -d
pytest

Safety model

• The server is read-only by default; INSERT/UPDATE/DELETE/DROP/ALTER and other write statements are blocked.
• Writes are only possible when the operator explicitly sets DATABASE_READ_ONLY=false and DATABASE_WRITE_ENABLED=true.
• Query results are capped by row count, timeout, and output size — runaway queries are prevented.

License

MIT