Database-MCP by fenil210 - MCP Server

DB-MCP: Universal Database MCP Server

Connect AI agents to any SQL database using the Model Context Protocol (MCP).

DB-MCP is a Python-based MCP server that lets AI agents query, analyze, and interact with your databases through natural language. Supports PostgreSQL, MySQL, SQL Server, and SQLite.

Installation

Quick Start (Recommended)

# Install from PyPI
pip install db-mcp

# Generate example configuration
db-mcp --init

# Edit config.json with your database details
# Then run the server
db-mcp --config config.json

Using db-mcp library in python

from db_mcp.config import Config
from db_mcp.database import DatabaseManager

config = Config("config.json")
db = DatabaseManager(config.get_database("my_database"))

result = db.execute_query("SELECT * FROM users")
if result["success"]:
    print(result["data"])

db.close()

That's it! Now configure your AI agent to connect to the server (see below).

System Architecture

graph LR
    A[AI Agent] -->|MCP Protocol| B[DB-MCP Server]
    B -->|SQLAlchemy| C[PostgreSQL]
    B -->|SQLAlchemy| D[MySQL]
    B -->|SQLAlchemy| E[SQLite]
    B -->|SQLAlchemy| F[SQL Server]
  
    G[config.json] -.->|Configuration| B
    H[.env] -.->|Credentials| B
  
    style A fill:#4CAF50
    style B fill:#2196F3
    style C fill:#336791
    style D fill:#4479A1
    style E fill:#003B57
    style F fill:#CC2927

Components:

AI Agent : Any MCP-compatible AI client (Claude Desktop, Cursor, etc.)
DB-MCP Server : Universal database adapter with security controls
SQLAlchemy : Database abstraction layer for multiple database types
Configuration : JSON config + environment variables for credentials

Query Flow Diagram

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as DB-MCP Server
    participant Pool as Connection Pool
    participant DB as Database
  
    Agent->>MCP: Natural Language Query
    Note over MCP: Parse request & validate
  
    MCP->>MCP: Security Check<br/>(read-only mode?)
  
    MCP->>Pool: Request connection
    Pool->>DB: Execute SQL
    DB->>Pool: Return results
    Pool->>MCP: Results (max 100 rows)
  
    MCP->>MCP: Format results as JSON
    MCP->>Agent: Structured response
  
    Note over Agent: Agent processes and<br/>presents to user

Flow Steps:

Agent sends natural language query via MCP protocol
DB-MCP validates and converts to SQL
Security checks applied (read-only enforcement)
Connection pooling manages database access
Results returned and formatted
Agent presents results to user

Features

Universal Connectivity : One server for PostgreSQL, MySQL, SQL Server, and SQLite
Secure by Default : Read-only mode, query validation, connection pooling
Easy Setup : Simple JSON configuration, works with any MCP-compatible agent
5 Powerful Tools : Query execution, schema inspection, explain plans, and more
PyPI Ready : Installable via pip for easy distribution

Complete Setup Guide

Step 1: Install DB-MCP

pip install db-mcp

Step 2: Install Database Drivers

Install the drivers you need for your database(s):

# For PostgreSQL
pip install psycopg2-binary

# For MySQL
pip install mysql-connector-python

# For SQL Server (Windows only)
pip install pyodbc

Note: SQLite support is built-in, no additional driver needed.

Step 3: Create Configuration

Generate an example config file:

db-mcp --init

This creates a config.json file with examples for all database types. Edit it with your actual database details:

{
  "databases": {
    "my_database": {
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "mydb",
      "username": "user",
      "password": "password",
      "read_only": true
    }
  }
}

Supported database types: postgresql, mysql, sqlite, mssql

Important: Remove database entries you don't need from config.json

Step 4: Test the Server

Run the server to make sure it connects:

db-mcp --config config.json

You should see:

==================================================
DB-MCP Server Starting...
==================================================
Loaded 1 database(s): my_database
Connected to database 'my_database' (postgresql)
Server ready and listening for connections
==================================================

Press Ctrl+C to stop the test.

Step 5: Connect Your AI Agent

For Claude Desktop

Edit your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

Windows:

{
  "mcpServers": {
    "database": {
      "command": "db-mcp",
      "args": [
        "--config",
        "C:\\path\\to\\your\\config.json"
      ]
    }
  }
}

Mac/Linux:

{
  "mcpServers": {
    "database": {
      "command": "db-mcp",
      "args": [
        "--config",
        "/path/to/your/config.json"
      ]
    }
  }
}

Important: Use absolute paths for config.json location.

For Other MCP-Compatible Agents

Configure according to your agent's MCP server setup instructions. The server communicates via standard MCP protocol over stdio.

Step 6: Restart Your AI Agent

Completely restart your AI agent to load the MCP server.

Usage Examples

Once connected, you can ask your agent questions like:

"What tables are in my database?"
"Show me the schema for the users table"
"How many active users do I have?"
"What are the top 10 products by sales?"
"Explain the query plan for selecting recent orders"
"Give me a sample of data from the customers table"

Your agent will automatically use the appropriate tools to query your database.

Configuration Reference

Database Configuration Options

{
  "databases": {
    "database_name": {
      "type": "postgresql",        // Required: postgresql, mysql, sqlite, mssql
      "host": "localhost",         // Required for all except SQLite
      "port": 5432,               // Optional: default port for each DB type
      "database": "dbname",       // Required: database name
      "username": "user",         // Required for most databases
      "password": "pass",         // Required for most databases
      "read_only": true,          // Optional: default true (recommended)
      "pool_size": 5,             // Optional: connection pool size (default 5)
      "max_overflow": 2,          // Optional: max extra connections (default 2)
      "pool_timeout": 30          // Optional: connection timeout (default 30s)
    }
  }
}

SQLite Configuration

{
  "databases": {
    "my_sqlite": {
      "type": "sqlite",
      "path": "./database.db",    // Path to SQLite file
      "read_only": false          // SQLite can be read-write
    }
  }
}

Using Environment Variables

You can reference environment variables in your config (recommended for passwords):

{
  "databases": {
    "prod": {
      "type": "postgresql",
      "host": "localhost",
      "username": "$DB_USER",      // Will read from environment
      "password": "$DB_PASSWORD"   // Will read from environment
    }
  }
}

Create a .env file:

DB_USER=myuser
DB_PASSWORD=mysecurepassword

Available Tools

Your AI agent has access to these 5 tools:

1. `list_databases`

Lists all configured databases.

2. `get_schema`

Get database schema information.

Without table name: Lists all tables and columns
With table name: Detailed schema for specific table

3. `execute_query`

Execute SQL queries (SELECT only in read-only mode).

Automatically limits results to 100 rows
Returns data in JSON format

4. `explain_query`

Get query execution plan without running the query.

Useful for query optimization
Shows how database will execute the query

5. `get_table_sample`

Quick preview of table data.

Returns first 10 rows by default
Fast way to inspect table contents

Security Best Practices

Always use read_only: true for production databases
Create dedicated read-only database users
Never commit passwords to version control
Use environment variables for sensitive credentials
Limit connection pool size to prevent overwhelming database
Review agent queries before allowing write access

Creating Read-Only Database Users

PostgreSQL:

CREATE USER readonly_user WITH PASSWORD 'password';
GRANT CONNECT ON DATABASE mydb TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;

MySQL:

CREATE USER 'readonly_user'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT ON mydb.* TO 'readonly_user'@'localhost';

Enabling Write Access

⚠️ WARNING: Write access allows your AI agent to modify data!

To allow INSERT, UPDATE, DELETE operations:

BACKUP YOUR DATABASE FIRST
Change "read_only": false in config.json
Ensure database user has write permissions
Restart your agent
Test thoroughly with non-critical data To allow INSERT, UPDATE, DELETE operations:
Change "read_only": false in config.json
Ensure database user has write permissions
Restart your agent
BACKUP YOUR DATABASE FIRST

See WRITE_ACCESS_GUIDE.md for detailed instructions and safety tips.

Development

Project Structure

db-mcp/
├── src/
│   └── db_mcp/
│       ├── __init__.py       # Package initialization
│       ├── server.py          # Main MCP server
│       ├── database.py        # Database connection manager
│       ├── tools.py           # MCP tool definitions
│       └── config.py          # Configuration handling
├── config.example.json        # Example configuration
├── requirements.txt           # Python dependencies
├── setup.py                   # PyPI packaging
└── README.md                  # This file

Running Tests

# Test with SQLite (no setup required)
echo '{"databases": {"test": {"type": "sqlite", "path": ":memory:", "read_only": false}}}' > test_config.json
python src/db_mcp/server.py --config test_config.json

Multi-Database Support

DB-MCP can connect to multiple databases simultaneously:

{
  "databases": {
    "prod_postgres": {
      "type": "postgresql",
      "host": "prod.server.com",
      "database": "production",
      "read_only": true
    },
    "staging_mysql": {
      "type": "mysql",
      "host": "staging.server.com",
      "database": "staging",
      "read_only": false
    },
    "local_sqlite": {
      "type": "sqlite",
      "path": "./local.db",
      "read_only": false
    }
  }
}

Your agent can then specify which database to query:

"Query the prod_postgres database"
"Show tables in staging_mysql"
"Add data to local_sqlite"

Performance Tuning

Connection Pooling

Adjust pool settings based on your workload:

{
  "pool_size": 10,        // Max persistent connections
  "max_overflow": 5,      // Additional connections during spikes
  "pool_timeout": 30,     // Wait time for available connection
  "pool_recycle": 3600    // Recycle connections after 1 hour
}

Query Optimization

Use explain_query tool to analyze query performance
Add indexes on frequently queried columns
Limit result sets (automatic 100-row limit)
Use connection pooling (enabled by default)

Troubleshooting

"Database not connected"

Check your database credentials in config.json
Verify the database server is running
Test connection with a database client first

"QueuePool limit exceeded"

Reduce pool_size in config
Check for long-running queries
Ensure connections are being properly released

"Only SELECT queries allowed"

Database is in read-only mode (by design for safety)
Change read_only: false if you need write access
Create a separate non-read-only database config

Windows ODBC Driver Issues (SQL Server)

Install "ODBC Driver 17 for SQL Server" from Microsoft
Download: https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server

"config.json not found"

Use absolute paths in Claude Desktop config
Run db-mcp --init to generate example config
Make sure you're in the right directory

Command not found: db-mcp

Make sure you installed with pip: pip install db-mcp
Try: python -m db_mcp.server --config config.json
Check if Python Scripts directory is in PATH

Supported Databases

Database	Driver	Connection String Format
PostgreSQL	psycopg2	`postgresql://user:pass@host:port/db`
MySQL	mysql-connector-python	`mysql+mysqlconnector://user:pass@host:port/db`
SQLite	built-in	`sqlite:///path/to/file.db`
SQL Server	pyodbc	`mssql+pyodbc://user:pass@host:port/db?driver=...`

Development & Contributing

Local Development Setup

If you want to contribute or modify the code:

# Clone the repository
git clone https://github.com/fenil210/Database-MCP
cd Database-MCP

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install all database drivers
pip install -e ".[all]"

Project Structure

db-mcp/
├── src/
│   └── db_mcp/
│       ├── __init__.py       # Package initialization
│       ├── server.py          # Main MCP server
│       ├── database.py        # Database connection manager
│       ├── tools.py           # MCP tool definitions
│       └── config.py          # Configuration handling
├── requirements.txt           # Python dependencies
├── setup.py                   # PyPI packaging
└── README.md                  # This file

Running Tests

# Test with SQLite (no setup required)
db-mcp --init
# Edit config.json to only include the my_sqlite_db entry
db-mcp --config config.json

Contributions welcome! Feel free to:

Add support for more databases
Improve error handling
Add more tools
Enhance documentation

License

MIT License - See LICENSE file for details

Support

For issues and questions:

GitHub Issues: https://github.com/fenil210/Database-MCP/issues
MCP Documentation: https://modelcontextprotocol.io/

Changelog

Version 0.1.0

Initial release
Support for PostgreSQL, MySQL, SQLite, SQL Server
5 core tools for database operations
Read-only mode by default
Connection pooling
Environment variable support
--init command for easy configuration

Acknowledgments

Built with the Model Context Protocol (MCP) by Anthropic. Uses SQLAlchemy for universal database connectivity.

Connect any AI agent to any database with DB-MCP!

Install now: pip install db-mcp

fenil210/Database-MCP

DB-MCP: Universal Database MCP Server

Installation

Quick Start (Recommended)

Using db-mcp library in python

System Architecture

Query Flow Diagram

Features

Complete Setup Guide

Step 1: Install DB-MCP

Step 2: Install Database Drivers

Step 3: Create Configuration

Step 4: Test the Server

Step 5: Connect Your AI Agent

For Claude Desktop

For Other MCP-Compatible Agents

Step 6: Restart Your AI Agent

Usage Examples

Configuration Reference

Database Configuration Options

SQLite Configuration

Using Environment Variables

Available Tools

1. list_databases

2. get_schema

3. execute_query

4. explain_query

5. get_table_sample

Security Best Practices

Creating Read-Only Database Users

Enabling Write Access

Development

Project Structure

Running Tests

Multi-Database Support

Performance Tuning

Connection Pooling

Query Optimization

Troubleshooting

"Database not connected"

"QueuePool limit exceeded"

"Only SELECT queries allowed"

Windows ODBC Driver Issues (SQL Server)

"config.json not found"

Command not found: db-mcp

Supported Databases

Development & Contributing

Local Development Setup

Project Structure

Running Tests

License

Support

Changelog

Version 0.1.0

Acknowledgments

1. `list_databases`

2. `get_schema`

3. `execute_query`

4. `explain_query`

5. `get_table_sample`