DB Explorer

DB Explorer MCP

A read-only Model Context Protocol (MCP) server for PostgreSQL, MySQL, and SQLite that lets an AI coding assistant explore, query, and audit a relational database without ever being able to write to it.

Point your MCP client at a database and ask questions in plain language. The client's LLM writes the SQL; this server parses it, refuses anything that is not a single read-only SELECT, executes it with a row cap, and returns structured results. Schema inspection, execution plans, index recommendations, and migration review come along with it.

MCP client LLM  ->  FastMCP tools  ->  safety layer  ->  SQLAlchemy  ->  database

(writes SQL) (7 tools) (rejects writes) (any dialect)

The server makes no LLM API calls of its own, so there is no API key to configure — reasoning happens in whichever client you connect. Works with SQLite, PostgreSQL, and MySQL through SQLAlchemy.

Tested and evaluated. 336 tests run on every push and pull request, plus 26 more against real PostgreSQL and MySQL in CI (Tests). In an agent evaluation, Claude completed 14 of 14 realistic database tasks through these tools with no failed tool calls, an average of 2 calls per task, and a mean independent judge score of 4.6 / 5 (Agent evals).

Why

Giving an assistant raw database credentials means one confused or prompt-injected turn can drop a table. Handing it a read-only replica loses schema context and plan analysis. This server takes the middle path: full introspection and query power, with mutation made structurally impossible at the parser level rather than by asking the model to behave.

Architecture

┌──────────────────────────────────────────────────────────────┐

│ MCP client (Claude Code / Claude Desktop / Inspector) │ │ owns the LLM: reads schema, authors SQL, interprets results │ └───────────────────────────┬──────────────────────────────────┘ │ MCP · stdio (local) │ · streamable HTTP + bearer token (remote) ┌───────────────────────────▼──────────────────────────────────┐ │ server.py — FastMCP instance + one engine per token group │ │ │ │ explore_schema execute_query explain_query │ │ validate_schema suggest_index migration_context │ │ validate_migration │ └──────┬───────────────────────┬───────────────────┬───────────┘ │ │ │ │ read path │ metadata path │ review path │ │ │ ┌──────▼────────────┐ ┌───────▼─────────┐ ┌──────▼──────────┐ │ safety.py │ │ inspector.py │ │ migration.py │ │ ── trust boundary │ │ schema_health.py│ │ parses up/down, │ │ sqlparse AST │ │ index_suggest.py│ │ never executes │ │ SELECT-only │ │ explain.py │ │ │ │ 1 stmt · no cmnts │ │ │ │ │ │ denylist · LIMIT │ │ │ │ │ └──────┬────────────┘ └───────┬─────────┘ └─────────────────┘ │ │ └───────────┬───────────┘ │ SQLAlchemy Core ┌──────────────────▼───────────────────────────────────────────┐ │ Target database · PostgreSQL / MySQL / SQLite │ └──────────────────────────────────────────────────────────────┘

The SQL arriving at safety.py is written by the client's model and therefore untrusted, so it is parsed rather than pattern-matched, and a rejected query never reaches the database.

Both modes run identical tool code — only MCP_TRANSPORT changes.

Quickstart

Requires Python 3.11+ and uv.

From PyPI

No clone needed. uvx downloads the package and runs it in its own environment:

claude mcp add db-explorer --env DATABASE_URL="postgresql+psycopg2://user:pass@localhost:5432/example" -- uvx db-explorer-mcp-server

Leave out --env to try it against the bundled demo database first. In any other client's config, use "command": "uvx" and "args": ["db-explorer-mcp-server"].

From source

git clone https://github.com/AYUSH-148/DB-Explorer-MCP

cd DB-Explorer-MCP uv sync uv run python seed_demo_db.py # creates sample.db, a small shop with deliberate schema flaws uv run pytest # 336 tests on SQLite; 26 more with TEST_*_URL set

On Windows, if uv is not on PATH, prefix with py -m (py -m uv sync).

You don't start the server yourself: your MCP client launches it over stdio, so go on to Connect a client. Run by hand, uv run server.py prints nothing and waits for a client on stdin; stop it with Ctrl+C.

The default database is sample.db. Point at your own with DATABASE_URL, either in the client config below or in a .env file copied from .env.example:

postgresql+psycopg2://user:password@localhost:5432/example

mysql+pymysql://user:password@localhost:3306/example sqlite:///C:/data/example.db

Percent-encode special characters in passwords (@ → %40, # → %23, / → %2F).

Connect a client

Claude Code — local

claude mcp add db-explorer --env DATABASE_URL="postgresql+psycopg2://user:pass@localhost:5432/example" -- uv --directory "C:/path/to/DB-Explorer-MCP" run server.py

Then run /mcp in a session to confirm the 7 tools are listed. Add -s user to make it available in every project.

Claude Code — remote

claude mcp add --transport http db-explorer https://your-deployment.fastmcp.app/mcp

Run /mcp → Authenticate for the OAuth flow; tokens are cached and refreshed automatically.

For a server you host yourself with a bearer token, send it as a header. Read it from an environment variable, so a .mcp.json committed for the team holds no secret:

{

"mcpServers": { "db-explorer": { "type": "http", "url": "https://dbx.example.com/mcp", "headers": { "Authorization": "Bearer ${DBX_TOKEN}" } } } }

Claude Desktop

Local, in claude_desktop_config.json:

{

"mcpServers": { "db-explorer": { "command": "uv", "args": ["--directory", "C:/path/to/DB-Explorer-MCP", "run", "server.py"], "env": { "DATABASE_URL": "postgresql+psycopg2://user:pass@localhost:5432/example" } } } }

To reach a remote deployment without a custom connector, proxy it over stdio:

{

"mcpServers": { "db-explorer": { "command": "npx", "args": ["-y", "mcp-remote", "https://your-deployment.fastmcp.app/mcp"] } } }

VS Code

.vscode/mcp.json is checked in and starts the server over stdio through the Windows py launcher. On macOS or Linux, change its command to uv and its args to ["run", "server.py"].

MCP Inspector

npx @modelcontextprotocol/inspector

Use transport Streamable HTTP with your /mcp URL, or stdio with uv run server.py. The Inspector shows raw tool responses and unparaphrased errors, which makes it the fastest way to tell a server problem from a client problem.

Python

import asyncio

from fastmcp import Client

async def main(): async with Client("https://your-deployment.fastmcp.app/mcp", auth="oauth") as client: print([tool.name for tool in await client.list_tools()]) print(await client.call_tool("explore_schema", {}))

asyncio.run(main())

Try it

Once connected to the demo sample.db from Quickstart, prompts like these work directly:

• *"What tables exist, and which ones are missing primary keys?"*
• *"Show me 5 rows from orders with the highest total."*
• *"Why is this query slow? SELECT * FROM orders WHERE created_at >= '2026-01-01'"*
• *"Which foreign keys in this database lack indexes? Give me the CREATE INDEX statements."*
• *"Draft a migration adding a shipped_at column to orders, then validate the up and down scripts."*

To watch the guardrails work, ask it to run DELETE FROM users. The call fails with Unsafe query blocked: Only SELECT queries are allowed. Got: DELETE and the database is untouched.

Agent skill

skill/db-explorer/SKILL.md is an optional agent skill that teaches the model to use these tools well: read the schema once before querying, compute totals in SQL rather than from returned rows, say when a result is truncated, and follow error hints instead of retrying. It guides the model only; the server must still be connected.

For Claude Code, copy the skill/db-explorer folder to ~/.claude/skills/db-explorer/ for every project, or to .claude/skills/db-explorer/ inside one project.

Tools

validate_schema reports four codes: missing_primary_key, unindexed_foreign_key, wide_table (50+ columns), and no_indexes. A foreign key counts as indexed when any index, the primary key, or a unique constraint starts with its columns; partial, GIN/GiST/BRIN and FULLTEXT/SPATIAL indexes do not count.

explore_schema is cheap by default: with no arguments it returns table names and column counts. Row counts arrive only with table_name (tables only, capped at 100,000 with row_count_capped: true). Narrow a large schema with name_pattern (order matches any name containing it, order_* is a glob), page with limit/offset, and use detail=true for the colu