Metadata-Version: 2.5
Name: db-explorer-mcp
Version: 0.1.0
Summary: An MCP server that lets Claude explore and query your databases
Author-email: Adarsh Yadav <yashyadav0171@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
Description-Content-Type: text/markdown

# DB Explorer — MCP Server

An MCP (Model Context Protocol) server that lets Claude explore and query your SQL databases.

## What It Does

Connect this server to Claude Desktop (or any MCP client) and Claude can:
- **List all tables** in your database with row counts
- **Describe table structure** — columns, types, primary keys, foreign keys
- *(Coming soon)* Run read-only SQL queries, explain query plans, and more

## Supported Databases

- SQLite (built-in, no extra setup)
- PostgreSQL (install with `pip install asyncpg`)
- MySQL (install with `pip install aiomysql`)

## Quick Start

### 1. Clone and install

```bash
git clone <your-repo-url>
cd db-explorer
pip install -e "."
```

### 2. Set up your database connection

```bash
cp .env.example .env
# Edit .env and set your DATABASE_URL
```

### 3. Create sample data (optional)

```bash
python seed_database.py
```

This creates a `sample.db` SQLite file with a mini e-commerce database (customers, products, orders).

### 4. Test the server

```bash
python -m db_explorer.server
```

### 5. Connect to Claude Desktop

Edit your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
**Windows:** `%AppData%\Claude\claude_desktop_config.json`

Add this:

```json
{
  "mcpServers": {
    "db-explorer": {
      "command": "python",
      "args": ["-m", "db_explorer.server"],
      "cwd": "/absolute/path/to/db-explorer"
    }
  }
}
```

Restart Claude Desktop. You should see "db-explorer" in the connectors menu.

### 6. Try it out!

Ask Claude:
- "What tables are in my database?"
- "Describe the orders table"
- "What's the structure of the customers table?"

## Project Structure

```
db-explorer/
├── .env                  # Your database URL (not committed to git)
├── .env.example          # Template for .env
├── pyproject.toml        # Project config and dependencies
├── seed_database.py      # Creates sample data for testing
├── sample.db             # Sample SQLite database (created by seed script)
├── README.md
└── src/db_explorer/
    ├── __init__.py
    ├── server.py          # MCP server + tool definitions
    ├── connection.py      # Database connection manager
    └── schema.py          # Schema inspection logic
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list_tables` | Lists all tables with row counts |
| `describe_table` | Shows columns, types, keys for a table |
| `run_query` | Runs read-only SQL queries (SELECT only) |
| `explain_query` | Shows the execution plan for a query |
| `get_table_stats` | Per-column null counts, distinct values, min/max |
| `get_indexes` | Shows indexes on a table |
| `get_relationships` | Maps all foreign keys across the whole database |
| `get_server_info` | Shows DB type, table count, and connection status |

## License

MIT