Database MCP Server

Database operations for AI agents — query, schema inspection, migrations, explain plans, performance analysis, and data exploration. 22 tools with read-only defaults and governed writes.

Architecture

Tools (22)

Schema Inspection (6)

| Tool | Purpose | |------|---------| | list_tables | All tables/collections in the database | | describe_table | Columns, types, constraints, indexes | | get_relationships | Foreign keys and references | | list_indexes | All indexes on a table | | get_database_stats | DB size, table sizes, row counts | | search_schema | Find tables/columns by name |

Querying (5)

| Tool | Purpose | Risk | |------|---------|------| | query | Execute read-only SQL (SELECT only) | read_only | | sample_data | Get sample rows from a table | read_only | | filter_table | Query with filters, ordering, pagination | read_only | | explain_query | Get EXPLAIN/query plan | read_only | | get_column_stats | Distinct values and distributions | read_only |

Write Operations (4)

| Tool | Purpose | Risk | |------|---------|------| | execute | Run INSERT/UPDATE/DELETE | gated_write | | create_index | Create an index | internal_write | | run_migration | Apply a schema migration | gated_write | | list_migrations | View migration history | read_only |

Performance (4)

| Tool | Purpose | |------|---------| | get_slow_queries | Queries exceeding duration threshold | | get_connections | Active connections and running queries | | get_maintenance_status | Table bloat, vacuum recommendations | | get_index_usage | Unused or missing indexes |

Utilities (3)

| Tool | Purpose | |------|---------| | generate_schema | Generate CREATE TABLE from description | | get_er_diagram | ER diagram data (tables + relationships) | | validate_sql | Check SQL syntax without executing |

Installation

cargo install mcp-database

Configuration

| Backend | Env Vars | Database | |---------|----------|----------| | Supabase | SUPABASE_URL + SUPABASE_SERVICE_KEY | PostgreSQL | | PlanetScale | PLANETSCALE_URL + PLANETSCALE_TOKEN | MySQL | | Neon | NEON_API_URL + NEON_API_KEY | PostgreSQL (serverless) | | Custom API | DATABASE_API_URL + DATABASE_API_KEY | Any (Postgres, MySQL, Mongo, SQLite) |

Client Configuration

{
  "mcpServers": {
    "database": {
      "command": "mcp-database",
      "args": [],
      "env": {
        "SUPABASE_URL": "https://xxx.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key"
      }
    }
  }
}

Usage Examples

Explore a database

"What tables are in this database?"
→ list_tables()
→ describe_table(table="users")
→ get_relationships(table="orders")
→ sample_data(table="users", limit=5)

Debug a slow query

"Why is this query slow?"
→ explain_query(sql="SELECT * FROM orders JOIN users ON ...")
→ get_index_usage() — find missing indexes
→ create_index(table="orders", columns=["user_id"])

Data exploration

"How many users signed up this month?"
→ query(sql="SELECT COUNT(*) FROM users WHERE created_at >= '2026-05-01'")
→ get_column_stats(table="users", schema="plan") — distribution by plan

Run a migration

"Add an email_verified column to users"
→ run_migration(name="add_email_verified", sql_up="ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT false")

Testing

Quick test (mock backend)

./test/run_tests.sh
# → 22/22 passed

Full lifecycle test (real SQLite)

# Terminal 1: Start real SQLite backend
cd test && python3 test_sqlite_backend.py

# Terminal 2: Run lifecycle test
cd test && python3 test_lifecycle.py

Output:

  ✅ 📦 CREATE TABLE users (0.48ms)
  ✅ 📦 CREATE TABLE orders (FK → users) (0.53ms)
  ✅ ➕ INSERT Alice (enterprise) → 1 row(s)
  ✅ ➕ INSERT Bob (pro) → 1 row(s)
  ✅ ➕ INSERT Carol (enterprise) → 1 row(s)
  ✅ ➕ INSERT order: Alice → Pro Plan $49 → 1 row(s)
  ✅ ➕ INSERT order: Alice → Enterprise Addon $99 → 1 row(s)
  ✅ ➕ INSERT order: Bob → Pro Plan $49 → 1 row(s)
  ✅ 📋 LIST TABLES → [_migrations, users, orders]
  ✅ 🔍 DESCRIBE users → (id, email, name, plan, created_at)
  ✅ 🔗 GET RELATIONSHIPS (orders → users)
  ✅ 📊 QUERY: revenue per user (JOIN + GROUP BY) → 3 rows
  ✅ 📊 QUERY: completed orders → 2 rows
  ✅ ⚡ CREATE INDEX orders(user_id) → idx_orders_user_id
  ✅ 📈 EXPLAIN → SEARCH orders USING INDEX idx_orders_user_id
  ✅ 📊 COLUMN STATS: users.plan → enterprise=2, pro=1
  ✅ 💾 DATABASE STATS → 8 rows across 3 tables
  ✅ 🗺️  ER DIAGRAM → 3 tables, 1 relationship
  ✅ 👀 SAMPLE DATA: users → 3 rows
  ✅ 📜 MIGRATION HISTORY → 2 migrations
  ✅ 🗑️  DROP TABLE orders
  ✅ 🗑️  DROP TABLE users
  ✅ 📋 VERIFY TABLES DROPPED → [_migrations]

  Results: 23/23 passed
  🎉 Full lifecycle complete!

Governance

• Read-only by default — query tool only allows SELECT statements
• Writes are gated — execute and run_migration are classified as gated writes
• No data stored — MCP is a pure API passthrough
• Parameterized queries — prevents SQL injection via params array

Custom API Spec

Build your own backend implementing these endpoints:

GET    /schema/tables
GET    /schema/tables/:name
GET    /schema/tables/:name/relationships
GET    /schema/tables/:name/indexes
GET    /schema/stats
GET    /schema/search?q=
GET    /schema/er-diagram
POST   /query                    {sql, params, limit, read_only}
POST   /query/explain            {sql}
POST   /query/validate           {sql}
GET    /tables/:name/sample?limit=
POST   /tables/:name/filter      {filter, limit, offset, order_by}
GET    /tables/:name/columns/:col/stats
POST   /execute                  {sql, params}
POST   /schema/indexes           {table, columns, unique}
POST   /migrations/run           {name, sql_up, sql_down}
GET    /migrations
GET    /performance/slow-queries
GET    /performance/connections
GET    /performance/maintenance
GET    /performance/index-usage
POST   /utils/generate-schema    {description}

License

Apache-2.0

Part of the ADK-Rust Enterprise MCP server ecosystem.

Built with ❤️ by Zavora AI