juliankgp/SQLBridgeMCP

SQLBridgeMCP 🚀

Connect any AI to your SQL database securely

SQLBridgeMCP is a secure bridge between AI assistants and your SQL databases. Configure once, use with any MCP-compatible AI tool.

✨ What can you do?

💬 "Claude, how many active users do we have?"
📊 "Show me sales by region for this month"
🔍 "Find all orders over $1000 from last week"

🎯 Works with

AI Tools: Claude Code • Claude API • GPT with MCP • Custom Apps
Databases: PostgreSQL • MySQL • SQLite • SQL Server
Your Data: Private • Secure • Under your control

🚀 Quick Start

1. Install

git clone <this-repo>
cd SQLBridgeMCP
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate  # Windows
pip install -r requirements.txt

2. Configure your database (Choose one method)

🚀 OPTION A: CONNECTION_STRING (Simpler)

cp .env.example .env
# Edit .env with ONE line:
DB_TYPE=sqlserver
CONNECTION_STRING=Server=localhost;Database=mydb;User Id=user;Password=pass;TrustServerCertificate=true

🔧 OPTION B: Individual Variables (Traditional)

cp .env.example .env  
# Edit .env with separate variables:
DB_TYPE=sqlserver
DB_HOST=localhost
DB_NAME=mydb  
DB_USER=myuser
DB_PASSWORD=mypass

3. Connect to your AI tool

Choose your AI platform and follow the specific setup:

🤖 Claude Code (Desktop App)

A. Using Claude CLI (Recommended):

# Add MCP server with CONNECTION_STRING
claude add mcp sql-bridge \
  --command "python" \
  --args "/path/to/SQLBridgeMCP/main.py" \
  --env DB_TYPE=sqlserver \
  --env CONNECTION_STRING="Server=localhost;Database=mydb;User Id=user;Password=pass;TrustServerCertificate=true"

# Or with individual variables
claude add mcp sql-bridge \
  --command "python" \
  --args "/path/to/SQLBridgeMCP/main.py" \
  --env DB_TYPE=postgresql \
  --env DB_HOST=localhost \
  --env DB_NAME=mydb \
  --env DB_USER=myuser \
  --env DB_PASSWORD=mypass

B. Manual config in claude_desktop_config.json:

🚀 With CONNECTION_STRING:

{
  "mcpServers": {
    "sql-bridge": {
      "command": "python",
      "args": ["/path/to/SQLBridgeMCP/main.py"],
      "env": {
        "DB_TYPE": "sqlserver",
        "CONNECTION_STRING": "Server=your-server;Database=your-db;User Id=user;Password=pass;TrustServerCertificate=true"
      }
    }
  }
}

🔧 Or with individual variables:

{
  "mcpServers": {
    "sql-bridge": {
      "command": "python", 
      "args": ["/path/to/SQLBridgeMCP/main.py"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "your-server",
        "DB_NAME": "your-database",
        "DB_USER": "your-user",
        "DB_PASSWORD": "your-password"
      }
    }
  }
}

B. Restart Claude Code completely

• Close Claude Code entirely
• Reopen Claude Code
• The MCP server will initialize automatically

C. Restart & Verify:

• Close Claude Code entirely → Reopen
• Look for the 🔌 MCP icon in Claude Code
• Try: "What MCP tools are available?"

🌐 Claude API (Programmatic)

import anthropic
from mcp_client import MCPClient

# Start MCP server
mcp = MCPClient(server_path="./main.py")

# Use with Claude API
client = anthropic.Anthropic(api_key="your-key")
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    messages=[{"role": "user", "content": "How many active employees?"}],
    tools=mcp.get_tools()  # Pass MCP tools
)

🔧 VS Code (with MCP Extensions)

# Install MCP extension for VS Code
code --install-extension mcp-integration

# Add to VS Code settings.json
{
  "mcp.servers": {
    "sql-bridge": {
      "command": "python",
      "args": ["/path/to/SQLBridgeMCP/main.py"],
      "env": {
        "DB_TYPE": "sqlserver",
        "CONNECTION_STRING": "your-connection-string"
      }
    }
  }
}

🤖 Other MCP-Compatible Clients

For any MCP client, use standard MCP protocol:

# Start the server
python /path/to/SQLBridgeMCP/main.py

# The server exposes these MCP tools:
# - execute_sql_query
# - list_tables  
# - describe_table
# - database_health
# - list_all_databases
# - list_tables_from_database

4. Start chatting with your data!

"Claude, show me the top 10 customers by revenue" ✨

🔧 How it works

You run your own server → Connects to your database → Works with any MCP client

[Your AI Tool] ──► [Your SQLBridgeMCP] ──► [Your Database]
                     (Your Config)         (Your Data)

🔒 Your data stays private - No third parties, no cloud services, just you.

🗃️ Database Support

🛡️ Security

• Read-only by default - Only SELECT queries allowed
• SQL injection protection - Input validation and sanitization
• Your credentials - Stored locally in your .env file
• No data sharing - Everything runs on your infrastructure

📖 Available MCP Tools

Your AI can use these 6 tools to interact with your database:

Core Database Operations

• execute_sql_query - Execute SELECT queries safely with parameters
  • Example: "Run a query to find active employees"
• list_tables - List all tables in the current database
  • Example: "What tables are available?"
• describe_table - Get detailed table schema and optionally sample data
  • Example: "Show me the structure of the Users table"

Database Management

• database_health - Check connection status and performance metrics
  • Example: "Is the database connection healthy?"
• list_all_databases - Show all databases in the SQL Server instance
  • Example: "What databases are available on this server?"
• list_tables_from_database - List tables from a specific database
  • Example: "Show tables in the 'Analytics' database"

🛡️ Security Features

• Read-only access - Only SELECT queries allowed
• Input validation - Prevents SQL injection attacks
• Query limits - Configurable timeouts and row limits
• Audit logging - All queries are logged for security

🚀 Advanced Usage

Example Usage with AI

💬 Natural Language Examples:

"How many active employees do we have?" → Uses execute_sql_query with SELECT COUNT(*) FROM Employees WHERE Active = 1

"Show me all the tables in our database" → Uses list_tables to display all available tables

"What's the structure of the Projects table?" → Uses describe_table with table_name="Projects"

"Is our database connection working properly?" → Uses database_health to check status and performance

Custom Applications

# Example: Using MCP tools programmatically
import asyncio
from mcp_client import MCPClient

async def get_employee_count():
    client = MCPClient(server_path="./main.py")
    result = await client.call_tool("execute_sql_query", {
        "query": "SELECT COUNT(*) as total FROM Employees WHERE Active = 1"
    })
    return result["data"][0]["total"]

# Get table information
async def explore_database():
    client = MCPClient(server_path="./main.py")
    
    # List all tables
    tables = await client.call_tool("list_tables")
    print(f"Found {tables['count']} tables")
    
    # Get schema for specific table
    schema = await client.call_tool("describe_table", {
        "table_name": "Employees",
        "include_sample_data": True
    })
    print(f"Employees table has {len(schema['schema'])} columns")

Multiple Databases

Configure different MCP servers for different databases in your Claude Code config.

Production Deployment

• Use Docker for containerization
• Configure SSL for database connections
• Set up monitoring and logging
• Create read-only database users

📋 Configuration Examples

🚀 With CONNECTION_STRING (Recommended)

SQL Server (Auto-parsing)

DB_TYPE=sqlserver
CONNECTION_STRING=Server=localhost;Database=mydb;User Id=sa;Password=MyPass123;TrustServerCertificate=true

PostgreSQL (SQLAlchemy format)

DB_TYPE=postgresql  
CONNECTION_STRING=postgresql+psycopg://user:pass@localhost:5432/mydb

MySQL (SQLAlchemy format)

DB_TYPE=mysql
CONNECTION_STRING=mysql+aiomysql://user:pass@localhost:3306/mydb

🔧 With Individual Variables (Fallback)

PostgreSQL

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=myuser
DB_PASSWORD=mypass

MySQL

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=mydb
DB_USER=myuser
DB_PASSWORD=mypass

SQLite (always uses individual variables)

DB_TYPE=sqlite
DB_NAME=/path/to/database.db

📋 Configuration Priority

1. CONNECTION_STRING (if provided)
2. Individual variables (DB_HOST, DB_USER, etc.)
3. Error if neither is configured

🛠️ Troubleshooting

MCP Not Connecting?

1. Restart Claude Code completely (close & reopen)
2. Check your claude_desktop_config.json syntax
3. Verify the path to main.py is correct (use full absolute path)
4. Ensure your .env file has correct credentials

Database Connection Issues?

1. Test your CONNECTION_STRING/credentials outside MCP first
2. Check if your database server is running
3. Verify firewall/network access to database
4. Use individual variables if CONNECTION_STRING fails

Python/Dependencies Issues?

# Verify Python and dependencies
python --version  # Should be 3.11+
pip install -r requirements.txt
python main.py  # Test server directly

Common Fixes:

• "No MCP icon": Restart Claude Code completely
• "Connection failed": Check database credentials
• "Python not found": Use full path to python in config
• "Module not found": Run pip install -r requirements.txt

🆘 Support

• 🐛 Issues: Report problems via GitHub Issues
• 💬 Questions: Start a discussion in GitHub Discussions
• 📧 Direct support: Check repository for contact info

🔗 Tested MCP Clients

Quick Setup Commands:

# Claude Code (Primary)
claude add mcp sql-bridge --command python --args /path/to/main.py --env DB_TYPE=sqlserver --env CONNECTION_STRING="your-string"

# Manual test (any platform)
python /path/to/SQLBridgeMCP/main.py

# Verify tools available
curl -X POST http://localhost:3000/mcp/list_tools

Built with ❤️ for the MCP community

SQLBridgeMCP - Your personal bridge between AI and your data