Universal Db Mcp

<p align="center"> <img src="assets/logo.png" alt="Universal DB MCP Logo" width="200"> </p> <h1 align="center">Universal DB MCP</h1> <p align="center"> <strong>Connect AI to Your Database with Natural Language</strong> </p> <p align="center"> A universal database connector implementing the Model Context Protocol (MCP) and HTTP API, enabling AI assistants to query and analyze your databases using natural language. Works with Claude Desktop, Cursor, Windsurf, VS Code, ChatGPT, and 50+ other platforms. </p> <p align="center"> <a href="https://www.npmjs.com/package/universal-db-mcp"><img src="https://img.shields.io/npm/v/universal-db-mcp.svg?style=flat-square&color=blue" alt="npm version"></a> <a href="https://www.npmjs.com/package/universal-db-mcp"><img src="https://img.shields.io/npm/dm/universal-db-mcp.svg?style=flat-square&color=green" alt="npm downloads"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square" alt="Node.js Version"></a> <a href="https://github.com/Anarkh-Lee/universal-db-mcp/stargazers"><img src="https://img.shields.io/github/stars/Anarkh-Lee/universal-db-mcp?style=flat-square" alt="GitHub Stars"></a> </p> <p align="center"> <a href="#-features">Features</a> • <a href="#-quick-start">Quick Start</a> • <a href="#-supported-databases">Databases</a> • <a href="#-documentation">Docs</a> • <a href="#-contributing">Contributing</a> </p> <p align="center"> <a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文文档</a> </p>

---

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.

---

<p align="center"> Made with ❤️ by <a href="https://github.com/Anarkh-Lee">Anarkh-Lee</a> </p>