shivanandham/multi-database-mcp

Multi-Database MCP Server

A comprehensive Model Context Protocol (MCP) server that provides unified access to multiple databases through a single interface. Perfect for developers who work with multiple databases and want seamless integration with AI-powered IDEs like Cursor.

✨ Why This Exists

Traditional MCP database servers require you to:

• ❌ Manually configure each database in your IDE's MCP settings
• ❌ Create separate MCP server instances for each database
• ❌ Restart your IDE when adding new databases
• ❌ Manage multiple connection configurations

This server solves all of that by providing:

• ✅ Single MCP server that handles all your databases
• ✅ Dynamic database switching without restarts
• ✅ Auto-discovery from a simple configuration file
• ✅ Unified interface for all database operations

🚀 Features

• Multi-Database Support: Connect to multiple PostgreSQL databases simultaneously
• Dynamic Database Switching: Switch between databases on-the-fly without restarting
• Unified Interface: Single MCP server handles all your database connections
• Auto-Discovery: Automatically discovers databases from configuration
• Rich Query Interface: Execute SQL queries, explore schemas, and manage data
• AI Agent Integration: Add and manage databases through AI agents and chat interfaces
• Cursor Integration: Seamless integration with Cursor IDE's AI features

🛠️ Available Tools

📋 Prerequisites

• Node.js 18.0.0 or higher
• PostgreSQL databases you want to connect to
• Cursor IDE (or any MCP-compatible IDE)

🚀 Quick Start

Option 1: Simple Installation (Recommended)

No cloning or npm install required! Just add this to your Cursor configuration:

1. Add to your .cursor/mcp.json file:

{
  "mcpServers": {
    "multi-database": {
      "command": "npx",
      "args": ["-y", "multi-database-mcp"]
    }
  }
}

2. Restart Cursor - That's it! The MCP server will be automatically downloaded and run when needed.

Option 2: Manual Installation

If you prefer to install manually:

# Clone the repository
git clone https://github.com/shivanandham/multi-database-mcp.git
cd multi-database-mcp

# Install dependencies
npm install

2. Configure Your Databases

You have two options to configure your databases:

Option A: Via AI Agent/Chat (Recommended)

📹 Video Demo: How to Add a Database Initially - See how to add a database using AI agent/chat interface

Simply ask your AI agent to add databases using natural language:

• "Add a database with URL postgresql://user:password@localhost:5432/main_app"
• "Connect to my analytics database at postgresql://user:password@localhost:5432/analytics"

The AI agent will automatically:

• Test the connection
• Extract the database name
• Add it to your configuration
• Make it immediately available

Option B: Via File Configuration

Copy the example configuration and edit it manually:

# Copy the example configuration
cp databases.example.json databases.json

Then edit databases.json to add your database connections:

{
  "databases": [
    {
      "name": "main_app",
      "type": "postgresql",
      "url": "postgresql://user:password@localhost:5432/main_app",
      "description": "Main application database"
    },
    {
      "name": "analytics",
      "type": "postgresql",
      "url": "postgresql://user:password@localhost:5432/analytics",
      "description": "Analytics and reporting database"
    },
    {
      "name": "staging",
      "type": "postgresql",
      "url": "postgresql://user:password@localhost:5432/staging",
      "description": "Staging environment database"
    }
  ]
}

3. Configure Cursor IDE (Manual Installation Only)

If you chose manual installation, add the MCP server to your Cursor configuration (~/project_root_directory/.cursor/mcp.json):

{
  "mcpServers": {
    "multi-database": {
      "command": "node",
      "args": [
        "/path/to/multi-database-mcp/server.js"
      ]
    }
  }
}

4. Restart Cursor

Restart Cursor IDE to load the new MCP server.

📹 Video Demo: Auto-Switch/Load Database on Startup - See how the database automatically switches/loads on MCP server startup

💡 Usage Examples

List Available Databases

list_databases

Switch to a Database

# Switch to specific database
switch_database database_name="analytics"

# Auto-detect from workspace (looks for .cursor/database.json)
switch_database

# Auto-detect from specific workspace path
switch_database workspace_path="/path/to/project"

Note: If you have a .cursor/database.json file in your workspace, the MCP server will automatically switch to the primary database when it starts up.

List Tables in Current Database

list_tables

Query the Database

query_database sql="SELECT * FROM users LIMIT 10"

Get Table Schema

describe_table table_name="users"

Add a New Database

Via AI Agent/Chat: Simply ask your AI agent: "Add a production database with URL postgresql://user:pass@prod.example.com:5432/prod_db"

Via Direct Command:

add_database url="postgresql://user:pass@prod.example.com:5432/prod_db"

📹 Video Demo: Production Database Management - See how to add a production database and switch between local and production databases

🔧 Configuration

Database Configuration (databases.json)

Each database entry supports:

• name: Unique identifier for the database
• type: Database type (currently only "postgresql" supported)
• url: PostgreSQL connection string
• description: Human-readable description

Connection String Format

postgresql://username:password@host:port/database_name

Examples:

• Local database: postgresql://postgres:password@localhost:5432/mydb
• Remote database: postgresql://user:pass@db.example.com:5432/production
• With SSL: postgresql://user:pass@host:5432/db?sslmode=require

🛠️ Testing Your Setup

Test your database connections:

# Test all database connections
npm test

➕ Adding New Databases

Method 1: Via AI Agent/Chat Interface (Recommended)

Use the add_database tool directly through AI agents or chat interfaces:

Required:

• url - PostgreSQL connection string

Optional:

• name - Custom database name (defaults to database name from URL)
• description - Human-readable description

Examples:

# Minimal - just URL (name extracted from URL)
add_database url="postgresql://user:password@localhost:5432/new_database"

# With custom name
add_database name="my_custom_name" url="postgresql://user:password@localhost:5432/new_database"

# With description
add_database url="postgresql://user:password@localhost:5432/new_database" description="My new database"

# Full example with all options
add_database name="production" url="postgresql://user:pass@prod.example.com:5432/prod_db" description="Production database"

The database name will be automatically extracted from the URL if not provided (e.g., "new_database" from the URL above).

Method 2: Manual Configuration

Edit databases.json and add a new entry:

{
  "name": "new_database",
  "type": "postgresql",
  "url": "postgresql://user:password@localhost:5432/new_database",
  "description": "My new database"
}

Benefits of using AI agents/chat interface:

• ✅ Connection testing - Validates the database before adding
• ✅ Automatic name extraction - Database name extracted from URL
• ✅ Automatic saving - Updates the configuration file
• ✅ Immediate availability - No restart required
• ✅ Error handling - Clear error messages for invalid connections
• ✅ Natural language - Add databases using conversational commands
• ✅ AI assistance - Get help with connection strings and troubleshooting

🏗️ Workspace-Based Database Detection

Create a .cursor/database.json file in your project root to enable automatic database detection:

{
  "primary_database": "luma",
  "databases": [
    {
      "name": "luma",
      "type": "postgresql",
      "url": "postgresql://postgres@localhost:5432/luma",
      "description": "Main project database"
    }
  ]
}

Benefits:

• ✅ Project-specific - Each project can have its own database config
• ✅ Team-friendly - Share database configuration with your team
• ✅ Auto-detection - Use switch_database without specifying database name
• ✅ Auto-switch on startup - Automatically switches to primary database when MCP server starts
• ✅ Version controlled - Commit database config to your project repo

🔍 Troubleshooting

Common Issues

"No database selected" error

• Use switch_database to select a database first

Connection failed

• Check your database credentials in databases.json
• Ensure PostgreSQL is running and accessible
• Verify network connectivity for remote databases

MCP server not loading

• Check the path in your Cursor MCP configuration
• Ensure Node.js dependencies are installed (npm install)
• Restart Cursor after configuration changes

Testing Your Setup

# Test database connections
npm test

🏗️ Architecture

The Multi-Database MCP Server consists of:

• server.js: Main MCP server implementation
• databases.json: Database configuration file
• test.js: Database connection testing script
• package.json: Node.js dependencies and scripts

🎯 What Makes This Different

Unlike existing solutions:

• No separate MCP servers - One server handles all databases
• No manual IDE configuration - Add databases to config file, not IDE settings
• No restarts required - Switch databases dynamically
• No connection management - Automatic connection pooling and cleanup

Built for developers who:

• Work with multiple databases (dev, staging, production)
• Want seamless AI-powered database exploration
• Need to switch between databases frequently
• Prefer configuration over manual setup

🔒 Security Considerations

• Never commit databases.json with real credentials to version control
• Use environment variables for sensitive connection strings
• Consider using connection pooling for production environments
• Regularly rotate database passwords

🤝 Contributing

1. Fork the 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

🚀 For Maintainers

If you're maintaining this package, see the guide for:

• Publishing to npm
• Version management
• Release workflows
• Package maintenance

📝 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol framework
• Inspired by the need for unified database access in AI-powered development environments
• Thanks to the MCP community for the excellent SDK and documentation

📞 Support

• Issues: GitHub Issues
• Documentation: Wiki

Made with ❤️ for the developer community