🤔 What is this?

This is a Model Context Protocol (MCP) server — a bridge that lets AI assistants interact with your databases directly.

Think of it like this: Instead of you manually writing SQL queries and copy-pasting results to ChatGPT, this server lets the AI connect to your database, explore the schema, run queries, and analyze data — all through natural conversation.

How it works

┌──────────────────┐         ┌─────────────────────────┐         ┌──────────────┐
│   AI Assistant    │   MCP   │   Database Explorer     │   SQL   │   Database   │
│                   │◄───────►│   MCP Server            │◄───────►│              │
│  Claude Desktop   │  JSON   │                         │         │  PostgreSQL  │
│  Cursor           │  over   │  • Explores schemas     │         │  MySQL       │
│  VS Code Copilot  │  stdio  │  • Runs queries         │         │  SQLite      │
│  Windsurf         │         │  • Generates ERDs       │         │  MongoDB     │
│  Any MCP client   │         │  • Suggests indexes     │         │              │
└──────────────────┘         └─────────────────────────┘         └──────────────┘

Who is this for?

• Developers who want to query databases using natural language through their AI coding assistant
• Data analysts who want AI help exploring and understanding databases
• Teams who want to let AI tools safely access their databases (with read-only mode)
• Anyone using an MCP-compatible AI tool who works with databases

⚠️ Important: This is NOT a standalone tool

This server requires an MCP-compatible AI client to use. It does NOT have its own UI.
The AI client sends commands to this server, and the server talks to your database. See Setup Guides below.

✨ Features

🚀 Quick Start

1. Clone and build

git clone https://github.com/nandanosql/database-explorer-mcp.git
cd database-explorer-mcp
npm install
npm run build

2. Add to your AI tool

Choose your AI tool below and add the configuration:

3. Start using it!

Just talk to your AI naturally:

"Connect to my SQLite database at ~/data/app.db"
"What tables are in this database?"
"Show me the first 10 users ordered by signup date"
"Generate an ER diagram of the schema"
"Any missing indexes I should add?"

🔧 Setup with Your AI Tool

{
  "mcpServers": {
    "database-explorer": {
      "command": "node",
      "args": ["/FULL/PATH/TO/database-explorer-mcp/build/index.js"],
      "env": {
        "DB_EXPLORER_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "database-explorer": {
      "command": "node",
      "args": ["/FULL/PATH/TO/database-explorer-mcp/build/index.js"]
    }
  }
}

{
  "servers": {
    "database-explorer": {
      "command": "node",
      "args": ["/FULL/PATH/TO/database-explorer-mcp/build/index.js"]
    }
  }
}

{
  "mcpServers": {
    "database-explorer": {
      "command": "node",
      "args": ["/FULL/PATH/TO/database-explorer-mcp/build/index.js"]
    }
  }
}

# The server reads from stdin and writes to stdout
node /path/to/database-explorer-mcp/build/index.js

npx @modelcontextprotocol/inspector node build/index.js

🛠️ Tools (13 total)

Connection Management

Schema Exploration

Querying & Analysis

Optimization & Export

🧠 Built-in Prompts

These prompts appear as suggested starting points in compatible AI clients:

📖 Usage Examples

Connect to a Database

You: Connect to my PostgreSQL database at localhost, database 'myapp', user 'admin', password 'secret'

AI: ✅ Connected to postgresql database "myapp" with alias "default"

Explore Schema

You: What tables are in this database?

AI: Database: myapp (postgresql)
──────────────────────────────────────────────────
  • users  [table]  —  12,450 rows  —  4.2 MB
  • orders  [table]  —  89,120 rows  —  28.7 MB
  • products  [table]  —  2,340 rows  —  1.1 MB
  ...

Query Data

You: Show me the top 5 customers by total order value

AI: [runs the query automatically]
customer_name │ total_orders │ total_value
──────────────┼──────────────┼────────────
Alice Johnson │ 47           │ $12,450.00
Bob Smith     │ 38           │ $9,870.50
...

Generate ERD

You: Generate an ER diagram of the database

AI: [returns Mermaid diagram]

erDiagram
    users {
        int id PK
        varchar username "NOT NULL"
        varchar email "NOT NULL"
    }
    orders {
        int id PK
        int user_id FK
        decimal total_amount "NOT NULL"
    }
    users ||--o{ orders : "user_id"

Search Data

You: Find any mentions of "alice" across all tables

AI: 🔍 Search results for "alice":
══════════════════════════════════════════════════

📋 users.username — 1 match(es)
  → id: 1 | username: alice | email: [email protected]

📋 users.email — 1 match(es)
  → id: 1 | username: alice | email: [email protected]

SQLite (File-based, no server needed)

You: Connect to the SQLite database at /path/to/mydb.sqlite

MongoDB

You: Connect to MongoDB at localhost, database 'myapp'
You: Find all users older than 25

⚙️ Configuration

Configure via environment variables in your MCP client config:

Example with Claude Desktop:

{
  "mcpServers": {
    "database-explorer": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "DB_EXPLORER_READONLY": "true",
        "DB_EXPLORER_MAX_ROWS": "200"
      }
    }
  }
}

🔒 Security

• Read-only by default — DROP, TRUNCATE, ALTER, INSERT, UPDATE, DELETE are blocked unless readonly: false is explicitly passed
• Auto-LIMIT — SELECT queries automatically get a LIMIT clause (default 100, max 1000)
• Query timeout — 30-second timeout prevents runaway queries
• No credentials stored — Connection details are in-memory only, never written to disk
• Local only — Uses stdio transport, no network exposure

🏗️ Project Structure

src/
├── index.ts              # Entry point (stdio transport + env config)
├── server.ts             # MCP server setup, tool/prompt/resource registration
├── types.ts              # Shared TypeScript interfaces + SQL safety patterns
├── connection-manager.ts # Connection lifecycle management
├── connectors/
│   ├── base.ts           # Abstract connector interface
│   ├── postgresql.ts     # PostgreSQL (pg driver)
│   ├── mysql.ts          # MySQL (mysql2 driver)
│   ├── sqlite.ts         # SQLite (better-sqlite3)
│   └── mongodb.ts        # MongoDB (mongodb driver)
└── tools/
    ├── connect.ts        # connect/disconnect/list
    ├── schema.ts         # list_tables/describe_table/get_schema
    ├── query.ts          # run_query/explain_query + SQL safety
    ├── stats.ts          # get_table_stats
    ├── optimize.ts       # suggest_indexes
    ├── export.ts         # export_data
    ├── erd.ts            # generate_erd (Mermaid)
    └── search.ts         # search_data

🧪 Testing

Integration tests use SQLite (no external database needed):

npm test

✔ connects to SQLite database
✔ lists all tables
✔ describes table with columns and types
✔ describes table with foreign keys
✔ gets indexes for a table
✔ gets full database schema
✔ runs SELECT query
✔ runs JOIN query
✔ runs aggregate query
✔ runs INSERT query (write mode)
✔ explains query plan
✔ gets table stats for all tables
✔ gets table stats for specific table
✔ blocks DROP statements
✔ blocks TRUNCATE statements
✔ blocks ALTER statements
✔ blocks INSERT statements
✔ allows SELECT statements
✔ allows EXPLAIN statements
✔ connects via connection manager
✔ lists connections
✔ throws on missing connection
✔ stores server config

23 pass / 0 fail

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork this repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Ideas for contributions

• Add support for more databases (Redis, DynamoDB, ClickHouse)
• Add query history tracking
• Add schema diff between connections
• Improve MongoDB aggregation pipeline support
• Add data visualization tools

📄 License

MIT — see LICENSE for details.