🗄️ DB MCP Gateway

Universal Database MCP Gateway - Orchestrate multiple database MCP servers through a unified interface.

Connect to PostgreSQL, MongoDB, MySQL, Redis, SQLite, and Supabase with a single MCP server!

🎯 Features

• ✅ Unified Interface - One MCP server to manage all your databases
• ✅ Auto-Discovery - Automatically discover and connect to configured databases
• ✅ Multi-Database Support - PostgreSQL, MongoDB, MySQL, Redis, SQLite, Supabase
• ✅ Smart Routing - Automatically routes queries to the correct database MCP server
• ✅ Auto-Spawn - Automatically spawns child MCP servers as needed
• ✅ Connection Management - Manage multiple database connections from one place
• ✅ Status Monitoring - Monitor all MCP server processes

📦 Installation

Option 1: Use directly with npx (Recommended)

npx db-mcp-gateway

Option 2: Install locally

npm install -g db-mcp-gateway

Option 3: Clone and build

git clone <your-repo-url>
cd db-mcp-gateway
npm install
npm run build

🚀 Quick Start

1. Configure Databases

Create a config/databases.json file:

{
  "databases": {
    "my-postgres": {
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "user": "postgres",
      "password": "password",
      "autoConnect": true
    },
    "my-mongodb": {
      "type": "mongodb",
      "uri": "mongodb://localhost:27017/myapp",
      "autoConnect": false
    }
  },
  "gateway": {
    "autoDiscovery": true,
    "autoSpawn": true,
    "maxConnections": 10
  }
}

2. Set Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
MONGODB_URI=mongodb://localhost:27017/myapp

3. Configure Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "db-gateway": {
      "command": "npx",
      "args": ["db-mcp-gateway"]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "db-gateway": {
      "command": "node",
      "args": ["/path/to/db-mcp-gateway/dist/index.js"]
    }
  }
}

4. Restart Claude Desktop

Restart Claude Desktop to load the MCP server.

🛠️ Available Tools

1. discover_databases

Discover all configured databases.

User: "What databases are available?"
Claude: Uses discover_databases tool

Parameters:

• scan (optional): Scan network for databases
• types (optional): Array of database types to discover

Returns:

{
  "discovered": [
    {
      "name": "my-postgres",
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "status": "available",
      "mcpServer": "postgres-mcp",
      "autoConnect": true
    }
  ],
  "count": 1
}

2. connect_database

Connect to a database (spawns the appropriate MCP server).

User: "Connect to my-postgres database"
Claude: Uses connect_database tool

Parameters:

• name (required): Name of the database
• type (optional): Database type (auto-detected)
• config (optional): Connection configuration

Returns:

{
  "success": true,
  "mcpServer": "postgresql-my-postgres",
  "pid": 12345,
  "tools": ["query", "list_tables", "describe_table"]
}

3. execute_query

Execute a query on any connected database.

User: "Get all users from my-postgres"
Claude: Uses execute_query tool

Parameters:

• database (required): Database name
• query (required): SQL string or MongoDB query object
• params (optional): Query parameters
• options (optional): Query options (timeout, explain)

Returns:

{
  "rows": [...],
  "rowCount": 10,
  "executionTime": 45,
  "database": "my-postgres",
  "mcpServer": "postgresql-my-postgres"
}

4. list_databases

List all connected databases.

User: "Show all connected databases"
Claude: Uses list_databases tool

Parameters:

• filter (optional): Filter by type or status

Returns:

{
  "databases": [
    {
      "name": "my-postgres",
      "type": "postgresql",
      "status": "connected",
      "mcpServer": "postgresql-my-postgres",
      "uptime": 3600
    }
  ]
}

5. get_mcp_status

Get status of all managed MCP servers.

User: "Show MCP server status"
Claude: Uses get_mcp_status tool

Returns:

{
  "servers": [
    {
      "name": "postgresql-my-postgres",
      "type": "postgresql",
      "status": "running",
      "pid": 12345,
      "uptime": 3600,
      "requestCount": 100,
      "errorCount": 0
    }
  ]
}

📚 Usage Examples

Example 1: Connect and Query PostgreSQL

User: "Connect to my-postgres and show all tables"

Claude:
1. Uses connect_database({ name: "my-postgres" })
2. Uses execute_query({
     database: "my-postgres",
     query: "SELECT tablename FROM pg_tables WHERE schemaname = 'public'"
   })

Result: Lists all tables

Example 2: Query MongoDB

User: "Connect to my-mongodb and find all active users"

Claude:
1. Uses connect_database({ name: "my-mongodb" })
2. Uses execute_query({
     database: "my-mongodb",
     query: {
       collection: "users",
       filter: { active: true }
     }
   })

Result: Returns active users

Example 3: Multi-Database Operations

User: "Show data from both PostgreSQL and MongoDB"

Claude:
1. Uses list_databases() to see available databases
2. Uses execute_query() on PostgreSQL
3. Uses execute_query() on MongoDB
4. Combines and presents results

🗂️ Supported Databases

| Database | Type | MCP Server Package | Status | |----------|------|-------------------|--------| | PostgreSQL | postgresql | @modelcontextprotocol/server-postgres | ✅ Supported | | MongoDB | mongodb | @executeautomation/mongodb-mcp-server | ✅ Supported | | MySQL | mysql | @benborla29/mcp-server-mysql | ✅ Supported | | Redis | redis | @modelcontextprotocol/server-redis | ✅ Supported | | SQLite | sqlite | @modelcontextprotocol/server-sqlite | ✅ Supported | | Supabase | supabase | @supabase/mcp | ✅ Supported |

⚙️ Configuration

Database Configuration

Each database entry in config/databases.json supports:

{
  "name": "unique-name",
  "type": "postgresql|mongodb|mysql|redis|sqlite|supabase",

  // SQL Databases (PostgreSQL, MySQL)
  "host": "localhost",
  "port": 5432,
  "database": "dbname",
  "user": "username",
  "password": "password",
  "ssl": false,

  // MongoDB
  "uri": "mongodb://localhost:27017/dbname",

  // Redis
  "uri": "redis://localhost:6379",

  // Supabase
  "url": "https://xxx.supabase.co",
  "key": "your-key",

  // Gateway Options
  "autoConnect": true
}

Gateway Configuration

{
  "gateway": {
    "autoDiscovery": true,    // Auto-discover databases
    "autoSpawn": true,        // Auto-spawn MCP servers
    "defaultDatabase": "my-postgres",
    "maxConnections": 10
  }
}

Environment Variables

Use environment variables for sensitive data:

{
  "password": "${POSTGRES_PASSWORD}"
}

The gateway will automatically replace ${VAR_NAME} with the value from environment variables.

🏗️ Architecture

┌─────────────────────────────┐
│   Claude Desktop / Cursor   │
└──────────────┬──────────────┘
               │
               │ MCP Protocol
               │
┌──────────────▼──────────────┐
│     DB MCP Gateway          │
│  (Your unified MCP server)  │
└──────┬──────┬──────┬────────┘
       │      │      │
  ┌────▼─┐ ┌─▼───┐ ┌▼────┐
  │ PG   │ │Mongo│ │Redis│
  │ MCP  │ │ MCP │ │ MCP │
  └────┬─┘ └─┬───┘ └┬────┘
       │     │      │
  ┌────▼─────▼──────▼────┐
  │   Actual Databases    │
  └───────────────────────┘

🔧 Development

Build

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

📝 Troubleshooting

Issue: "Database not found"

Solution: Make sure the database is configured in config/databases.json

Issue: "Connection failed"

Solution:

1. Check your database is running
2. Verify credentials in .env
3. Check firewall/network settings

Issue: "MCP server failed to spawn"

Solution:

1. Ensure the required MCP server package is installed
2. Check Node.js version (requires >= 18.0.0)
3. Check logs in stderr

Issue: "Environment variable not replaced"

Solution: Make sure your .env file is in the project root and contains the variable.

🎯 Use Cases

1. Multi-Database Development - Work with multiple databases simultaneously
2. Database Migration - Easily compare and migrate data between databases
3. Unified Analytics - Query multiple databases for comprehensive analytics
4. Cross-Database Operations - Perform operations across different database types
5. Simplified Configuration - Manage all database connections from one place

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🔗 Links

• Model Context Protocol Documentation
• Claude Desktop
• Cursor AI

🙏 Credits

Built with the Model Context Protocol SDK

Supported MCP Servers:

• @modelcontextprotocol/server-postgres
• @executeautomation/mongodb-mcp-server
• @benborla29/mcp-server-mysql
• @modelcontextprotocol/server-redis
• @supabase/mcp

Made with ❤️ for the MCP community