MCP Database Bridge

Demo Video

Click the preview below to watch the MCP Database Bridge project demonstration on YouTube.

Related MCP server: sqlite-mcp

✨ Features

• 🛡️ Read-Only Safeties: Strict regex filtering intercepts and rejects destructive operations like INSERT, UPDATE, DROP, and ALTER. The AI can look, but it can't touch.

• 🔍 Introspection: AI can autonomously list tables and read schemas (PRAGMA table_info) directly to understand your data structure before writing queries.

• 🚀 Claude Desktop Ready: Comes with one-click automated setup scripts for both macOS/Linux and Windows that instantly wire it up to your Claude Desktop config.

• 📊 Query Analysis: Includes explain_query capabilities to help AI debug complex data retrieval.

Quick Start

The setup scripts create a Python virtual environment, install dependencies, and register database-mcp in Claude Desktop.

Hosted Custom Client

Run the ChatGPT-inspired DB/BRIDGE client locally:

export GROQ_API_KEY=your_groq_api_key
uvicorn client.api.app:app --reload

Open http://127.0.0.1:8000 to select a Groq model, manage temporary SQLite databases, ask questions, and inspect the MCP tool activity used for each answer.

Vercel Deployment

The hosted client is configured through vercel.json. Add these environment variables in Vercel before deploying:

GROQ_API_KEY=your_groq_api_key
GROQ_MODELS=llama-3.3-70b-versatile,llama-3.1-8b-instant,openai/gpt-oss-120b
ALLOWED_ORIGINS=https://your-docs-domain.example,https://your-vercel-app.vercel.app

Uploaded databases are isolated by anonymous browser session but remain temporary because Vercel's function filesystem is not durable.

Prerequisites

• Python 3.11 or newer

• Git

• Claude Desktop

1. Clone the Repository

git clone https://github.com/buvaneswaraneb/mcp-database-bridge.git
cd mcp-database-bridge

2. Run the Setup Script

Choose the instructions for your operating system.

Run:

chmod +x setup.sh
./setup.sh

After setup completes:

1. Completely quit Claude Desktop.

   • On macOS, press Cmd + Q.

   • On Linux, quit Claude from the application menu.

2. Reopen Claude Desktop.

3. Open a new chat and confirm that database-mcp appears in the available tools.

Run setup.bat from Command Prompt:

setup.bat

You can also double-click setup.bat from File Explorer.

Completely Restart Claude Desktop on Windows

Closing the Claude window may leave it running in the background. Fully stop it before reopening:

1. Press Ctrl + Shift + Esc to open Task Manager.

2. Select the Processes tab.

3. Find Claude under Apps or Background processes.

4. Select each Claude process and click End task.

5. Wait a few seconds, then reopen Claude Desktop.

If Claude does not appear under Processes, open the Details tab and end any Claude.exe processes.

3. Verify the Connection

In Claude Desktop:

1. Open a new chat.

2. Open the tools or integrations menu.

3. Confirm that database-mcp is connected.

4. Ask: What databases are available?

If the server is not listed, completely stop Claude Desktop again and reopen it.

🛠️ Manual Setup (Claude Code / Custom Agents)

If you prefer to configure things manually or use Claude Code in your terminal:

1. Create Virtual Environment & Install Dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   cp .env.example .env

2. Add to Claude Code:

   claude mcp add database-mcp .venv/bin/python mcp/src/server.py

🧪 Running Tests

Ensure everything is working correctly by running the comprehensive test suite:

pytest mcp/tests/ -v

🏗️ Architecture & Internals

graph TD
    A[🤖 Claude Desktop / AI Agents] <-->|stdio JSON-RPC| B{MCP Bridge Router}
    
    subgraph Database MCP Server
        B -->|tools/call: list_tables| C[📋 list_tables]
        B -->|tools/call: get_schema| D[🔍 get_schema]
        B -->|tools/call: explain_query| E[📊 explain_query]
        B -->|tools/call: run_select| F[▶️ run_select]
        
        F --> G{🛡️ Read-Only Safeties}
        G -. Block UPDATE/DROP/INSERT .-> H[❌ Reject]
        G -- Allow SELECT --> I[✅ Execute]
    end

    C & D & E & I --> J[(🗄️ SQLite Database)]
    
    style A fill:#4B32C3,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#2D3748,stroke:#4B32C3,stroke-width:2px,color:#fff
    style G fill:#9B2C2C,stroke:#FC8181,stroke-width:2px,color:#fff
    style J fill:#276749,stroke:#68D391,stroke-width:2px,color:#fff
    style H fill:#E53E3E,stroke:#fff,stroke-width:1px,color:#fff
    style C fill:#2A4365,stroke:#63B3ED,color:#fff
    style D fill:#2A4365,stroke:#63B3ED,color:#fff
    style E fill:#2A4365,stroke:#63B3ED,color:#fff
    style F fill:#2A4365,stroke:#63B3ED,color:#fff
    style I fill:#38A169,stroke:#fff,color:#fff

Curious how it works under the hood?

• Read documentation/docs/structure.md for a detailed walkthrough of the file architecture and the JSON-RPC execution flow.

• Read documentation/docs/ai_usage_note.md for notes on how AI was leveraged to build this project.