Universal Sql MCP Server

🚀 Universal SQL MCP Server

The Universal SQL MCP Server is a Model Context Protocol (MCP) server that offers secure access to multiple SQL database engines. It allows AI assistants and other MCP clients to interact with various SQL databases via a standardized interface.

🚀 Quick Start

Try the Demo (SQLite)

The quickest way to experience the Universal SQL MCP Server is as follows:

# Clone the repository
git clone <repository-url>
cd gen-http-sql-mcp

# Install dependencies
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# Run the demo (creates a SQLite database with sample data)
python demo.py

# Start the MCP server
python main.py

The demo creates a SQLite database with sample users and orders, then demonstrates all MCP tools.

✨ Features

• Multi-Database Support: Compatible with MySQL, PostgreSQL, SQLite, and SQL Server.
• Database Schema Inspection: Retrieve comprehensive information about all tables, columns, indexes, and constraints.
• Safe Query Execution: Execute SELECT queries with built - in security restrictions.
• Controlled Write Operations: Execute INSERT and UPDATE operations with proper security controls.
• Connection Testing: Verify database connectivity and configuration.
• Environment-based Configuration: Secure configuration through environment variables.
• Comprehensive Logging: Detailed logging for monitoring and debugging.
• Database-Specific Optimizations: Tailored queries and features for each database engine.

📦 Installation

1. Clone this repository:

git clone <repository-url>
cd gen-http-sql-mcp

2. Install dependencies:

# Using pip
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# Or using uv
uv sync

3. Optional: Install database-specific drivers only if needed:

# For MySQL only
pip install fastmcp mysql-connector-python python-dotenv

# For PostgreSQL only  
pip install fastmcp psycopg2-binary python-dotenv

# For SQLite only (no additional drivers needed)
pip install fastmcp python-dotenv

# For SQL Server only
pip install fastmcp pyodbc python-dotenv

📚 Documentation

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit the .env file with your database credentials:

MySQL Configuration

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

PostgreSQL Configuration

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

SQLite Configuration

DB_TYPE=sqlite
DB_NAME=/path/to/your/database.db
# Note: SQLite doesn't require host, port, user, or password

SQL Server Configuration

DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_DRIVER=ODBC Driver 17 for SQL Server

Common Optional Settings

# Optional: Connection pool settings (not applicable for SQLite)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Optional: Connection timeout settings (in seconds)
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30

# Optional: Enable write operations (INSERT/UPDATE) - set to true to enable
ENABLE_WRITE_OPERATIONS=false

Configuration Options

Database-Specific Notes

• SQLite: Only requires DB_NAME (file path). Connection pooling settings are ignored.
• SQL Server: May require additional ODBC driver installation and DB_DRIVER specification.
• PostgreSQL: Uses psycopg2-binary for optimal performance and compatibility.
• MySQL: Uses the official mysql-connector-python driver.

Usage

Running the Server

Start the MCP server:

uv run python main.py

The server will:

1. Load configuration from environment variables
2. Test the database connection
3. Start the MCP server and listen for requests

Using with MCP Clients

This server implements the Model Context Protocol and can be used with any MCP-compatible client. The server provides four tools that can be called by MCP clients.

Example Tool Calls

1. Get Database Schema:

{
  "method": "tools/call",
  "params": {
    "name": "get_database_schema"
  }
}

2. Execute SQL Query (works with all database types):

{
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "sql_query": "SELECT * FROM users LIMIT 10"
    }
  }
}

3. Execute Write Operation (works with all database types):

{
  "method": "tools/call",
  "params": {
    "name": "execute_write_operation",
    "arguments": {
      "sql_query": "INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')"
    }
  }
}

4. Test Connection:

{
  "method": "tools/call",
  "params": {
    "name": "test_database_connection"
  }
}

Database-Specific Query Examples

• PostgreSQL with RETURNING clause:

INSERT INTO users (name, email) VALUES ('Jane Doe', 'jane@example.com') RETURNING id;

• SQLite with autoincrement:

INSERT INTO users (name, email) VALUES ('Bob Smith', 'bob@example.com');

• SQL Server with OUTPUT clause:

INSERT INTO users (name, email) OUTPUT INSERTED.id VALUES ('Alice Johnson', 'alice@example.com');

🔧 Technical Details

Supported Databases

• MySQL: Full support with comprehensive schema information, including table comments, column details, and index information. Supports connection pooling and timeout configurations, uses mysql-connector-python for optimal compatibility.
• PostgreSQL: Full support with comprehensive schema information, advanced index information, and constraint details. Uses psycopg2-binary for high performance.
• SQLite: Full support, perfect for local development and testing. Provides complete table and column information, index details, and primary key information. No additional driver installation required.
• SQL Server: Full support with ODBC connectivity. Supports both Windows and SQL Server authentication. Uses ODBC connectivity via pyodbc and has configurable ODBC driver selection.

Project Structure

gen-http-sql-mcp/
├── main.py              # Main server entry point
├── database.py          # Universal database connection and management
├── tools.py             # MCP tools implementation
├── .env.example         # Environment configuration template
├── pyproject.toml       # Project dependencies and metadata
└── README.md           # This file

Dependencies

Error Handling

The server includes comprehensive error handling:

• Database connection errors are logged and reported.
• Invalid SQL queries are rejected with clear error messages.
• Configuration validation ensures required parameters are present.
• Graceful shutdown on interruption.

Logging

The server provides comprehensive logging capabilities:

Basic Logging

• Connection status and database information.
• Query execution results and performance.
• Error messages with context.
• Server startup and shutdown events.

Request Logging

The server includes advanced request logging middleware to help debug client connection issues:

Simple Request Logging (Default)

# Enabled by default, shows basic request information
ENABLE_REQUEST_LOGGING=true

Detailed Request Logging (Debug Mode)

# Enable detailed logging with headers and payloads
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUG

Docker Debug Environment

For debugging client connection issues, use the debug environment:

# Start debug environment with detailed logging
make debug

# View debug logs
make logs-debug

# View only MCP server debug logs
make logs-debug-mcp

The debug environment enables:

• Detailed request/response logging.
• HTTP headers logging.
• Request payload logging.
• Response payload logging.
• Execution timing.
• Client information tracking.

📄 License

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

Support

For issues and questions:

• Check the logs for error messages.
• Verify your database configuration.
• Ensure your database server is accessible.
• Create an issue in the repository.