Universal DB MCP

Why Universal DB MCP?

Imagine asking your AI assistant: "Show me the top 10 customers by order value this month" and getting instant results from your database - no SQL writing required. Universal DB MCP makes this possible by bridging AI assistants with your databases through the Model Context Protocol (MCP) and HTTP API.

You: "What's the average order value for users who signed up in the last 30 days?"

AI: Let me query that for you...

┌─────────────────────────────────────┐
│ Average Order Value: $127.45        │
│ Total New Users: 1,247              │
│ Users with Orders: 892 (71.5%)      │
└─────────────────────────────────────┘

✨ Features

• 17 Database Support - MySQL, PostgreSQL, Redis, Oracle, SQL Server, MongoDB, SQLite, and 10 Chinese domestic databases
• 55+ Platform Integrations - Works with Claude Desktop, Cursor, VS Code, ChatGPT, Dify, and 50+ other platforms
• Flexible Architecture - 2 startup modes (stdio/http) with 4 access methods: MCP stdio, MCP SSE, MCP Streamable HTTP, and REST API
• Security First - Read-only mode by default prevents accidental data modifications
• Intelligent Caching - Schema caching with configurable TTL for blazing-fast performance
• Batch Query Optimization - Up to 100x faster schema retrieval for large databases
• Schema Enhancement - Table comments, implicit relationship inference for better Text2SQL accuracy
• Multi-Schema Support - Automatic discovery of all user schemas (PostgreSQL, SQL Server, Oracle, DM, and more)
• Data Masking - Automatic sensitive data protection (phone, email, ID card, bank card, etc.)
• Connection Stability - Connection pooling, TCP Keep-Alive, and automatic reconnection for long-running sessions

Performance Improvements

🚀 Quick Start

Installation

npm install -g universal-db-mcp

MCP Mode (Claude Desktop)

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": [
        "universal-db-mcp",
        "--type", "mysql",
        "--host", "localhost",
        "--port", "3306",
        "--user", "root",
        "--password", "your_password",
        "--database", "your_database"
      ]
    }
  }
}

Restart Claude Desktop and start asking questions:

• "Show me the structure of the users table"
• "Count orders from the last 7 days"
• "Find the top 5 products by sales"

HTTP API Mode

# Set environment variables
export MODE=http
export HTTP_PORT=3000
export API_KEYS=your-secret-key

# Start the server
npx universal-db-mcp

# Test the API
curl http://localhost:3000/api/health

MCP SSE Mode (Dify and Remote Access)

When running in HTTP mode, the server also exposes MCP protocol endpoints via SSE (Server-Sent Events) and Streamable HTTP. This allows platforms like Dify to connect using the MCP protocol directly.

SSE Endpoint (Legacy):

GET http://localhost:3000/sse?type=mysql&host=localhost&port=3306&user=root&password=xxx&database=mydb

Streamable HTTP Endpoint (MCP 2025 Spec, Recommended):

POST http://localhost:3000/mcp
Headers:
  X-DB-Type: mysql
  X-DB-Host: localhost
  X-DB-Port: 3306
  X-DB-User: root
  X-DB-Password: your_password
  X-DB-Database: your_database
Body: MCP JSON-RPC request

See Dify Integration Guide for detailed setup instructions.

📊 Supported Databases

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         Universal DB MCP                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Startup Modes:                                                          │
│  ┌────────────────────────────┬────────────────────────────────────┐    │
│  │ stdio mode                 │ http mode                          │    │
│  │ (npm run start:mcp)        │ (npm run start:http)               │    │
│  └─────────────┬──────────────┴───────────────┬────────────────────┘    │
│                │                              │                          │
│                ▼                              ▼                          │
│  ┌─────────────────────────┐    ┌───────────────────────────────────┐   │
│  │      MCP Protocol       │    │           HTTP Server             │   │
│  │    (stdio transport)    │    │                                   │   │
│  │                         │    │  ┌─────────────────────────────┐  │   │
│  │  Tools:                 │    │  │      MCP Protocol           │  │   │
│  │  • execute_query        │    │  │  (SSE / Streamable HTTP)    │  │   │
│  │  • get_schema           │    │  │                             │  │   │
│  │  • get_table_info       │    │  │  Tools: (same as stdio)     │  │   │
│  │  • clear_cache          │    │  │  • execute_query            │  │   │
│  │  • get_enum_values      │    │  │  • get_schema               │  │   │
│  │  • get_sample_data      │    │  │  • get_table_info           │  │   │
│  │  • connect_database     │    │  │  • clear_cache              │  │   │
│  │  • disconnect_database  │    │  │  • get_enum_values          │  │   │
│  │  • get_connection_status│    │  │  • get_sample_data          │  │   │
│  │                         │    │  │  • connect_database         │  │   │
│  │  For: Claude Desktop,   │    │  │  • disconnect_database      │  │   │
│  │       Cursor, etc.      │    │  │  • get_connection_status    │  │   │
│  └─────────────┬───────────┘    │  │                             │  │   │
│                │                │  │  For: Dify, Remote Access   │  │   │
│                │                │  └──────────────┬──────────────┘  │   │
│                │                │                 │                 │   │
│                │                │  ┌──────────────┴──────────────┐  │   │
│                │                │  │        REST API             │  │   │
│                │                │  │                             │  │   │
│                │                │  │  Endpoints:                 │  │   │
│                │                │  │  • /api/connect             │  │   │
│                │                │  │  • /api/query               │  │   │
│                │                │  │  • /api/schema              │  │   │
│                │                │  │  • ... (10+ endpoints)      │  │   │
│                │                │  │                             │  │   │
│                │                │  │  For: Coze, n8n, Custom     │  │   │
│                │                │  └──────────────┬──────────────┘  │   │
│                │                └─────────────────┼─────────────────┘   │
│                │                                  │                     │
│                └──────────────────┬───────────────┘                     │
│                                   ▼                                     │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     Core Business Logic                           │  │
│  │  • Query Execution    • Schema Caching                           │  │
│  │  • Safety Validation  • Connection Management                    │  │
│  └──────────────────────────────────┬───────────────────────────────┘  │
│                                     ▼                                   │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                    Database Adapter Layer                         │  │
│  │  MySQL │ PostgreSQL │ Redis │ Oracle │ MongoDB │ SQLite │ ...    │  │
│  │        (Connection Pool + TCP Keep-Alive + Auto-Retry)           │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🔒 Security

By default, Universal DB MCP runs in read-only mode, blocking all write operations (INSERT, UPDATE, DELETE, DROP, etc.).

Permission Modes

Fine-grained permission control is supported for flexible configuration:

Permission Types:

• read - SELECT queries (always included)
• insert - INSERT, REPLACE
• update - UPDATE
• delete - DELETE, TRUNCATE
• ddl - CREATE, ALTER, DROP, RENAME

Usage Examples:

# Read-only mode (default)
npx universal-db-mcp --type mysql ...

# Read/write but no delete
npx universal-db-mcp --type mysql --permission-mode readwrite ...

# Custom: only read and insert
npx universal-db-mcp --type mysql --permissions read,insert ...

# Full control (equivalent to --danger-allow-write)
npx universal-db-mcp --type mysql --permission-mode full ...

Permission Configuration by Transport:

⚠️ Different transports use different parameter naming conventions!

Best Practices:

• Never enable write mode in production
• Use dedicated read-only database accounts
• Connect through VPN or bastion hosts
• Regularly audit query logs

🔌 Supported Platforms

Universal DB MCP works with any platform that supports the MCP protocol or REST API. Here's a comprehensive list:

AI-Powered Code Editors & IDEs

AI Coding Assistants

Desktop AI Chat Applications

Web-Based AI Platforms

Agent Frameworks & SDKs

CLI Tools & Terminal

Productivity & Automation

Messaging Platform Integrations

Local LLM Runners

Development & Testing Tools

Note: Any MCP-compatible client can connect via stdio (local) or SSE/Streamable HTTP (remote). Any HTTP client can use the REST API.

📚 Documentation

Getting Started

• Installation Guide
• Quick Start
• Configuration
• Usage Examples

Deployment

• Deployment Overview
• Local Deployment
• Docker Deployment
• Cloud Deployment

Database Guides

• Database Support Overview
• MySQL
• PostgreSQL
• More databases...

HTTP API

• API Reference
• Deployment Guide

Integrations

AI Editors & IDEs: Cursor | VS Code | JetBrains | Windsurf | Zed | Neovim | Emacs

AI Assistants: Claude Desktop | Claude Code | GitHub Copilot | Cline | Continue

AI Platforms: Dify | Coze | n8n | ChatGPT | LangChain

Desktop Apps: Cherry Studio | LM Studio | Jan | Ollama

Messaging: Slack | Discord

Tools: MCP Inspector | Postman

📁 View all 55 integration guides | 中文版本请在对应文档名后加 .zh-CN

Advanced

• Security Guide
• Multi-tenant Guide
• Architecture
• Troubleshooting

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a Pull Request.

# Clone the repository
git clone https://github.com/Anarkh-Lee/universal-db-mcp.git

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

📄 License

This project is licensed under the MIT License.

🌟 Star History

If you find this project useful, please consider giving it a star! Your support helps us continue improving Universal DB MCP.

📝 Changelog

See CHANGELOG.md for a detailed version history.