Universal DB MCP

Universal DB MCP

Enables AI assistants to query and analyze databases using natural language through MCP and HTTP API, supporting 17+ databases and integration with 50+ platforms.

Category
访问服务器

README

<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

Tables Before After Improvement
50 tables ~5s ~200ms 25x faster
100 tables ~10s ~300ms 33x faster
500 tables ~50s ~500ms 100x faster

🚀 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
Endpoint Method Description
/sse GET Establish SSE connection (legacy)
/sse/message POST Send message to SSE session
/mcp POST Streamable HTTP endpoint (recommended)
/mcp GET SSE stream for Streamable HTTP
/mcp DELETE Close session

See Dify Integration Guide for detailed setup instructions.

📊 Supported Databases

Database Type Default Port Category
MySQL mysql 3306 Open Source
PostgreSQL postgres 5432 Open Source
Redis redis 6379 NoSQL
Oracle oracle 1521 Commercial
SQL Server sqlserver 1433 Commercial
MongoDB mongodb 27017 NoSQL
SQLite sqlite - Embedded
Dameng (达梦) dm 5236 Chinese
KingbaseES kingbase 54321 Chinese
GaussDB gaussdb 5432 Chinese (Huawei)
OceanBase oceanbase 2881 Chinese (Ant)
TiDB tidb 4000 Distributed
ClickHouse clickhouse 8123 OLAP
PolarDB polardb 3306 Cloud (Alibaba)
Vastbase vastbase 5432 Chinese
HighGo highgo 5866 Chinese
GoldenDB goldendb 3306 Chinese (ZTE)

🏗️ 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:

Mode Allowed Operations Description
safe (default) SELECT Read-only, safest
readwrite SELECT, INSERT, UPDATE Read/write but no delete
full All operations Full control (dangerous!)
custom Custom combination Specify via --permissions

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!

Transport Parameter Location Permission Mode Custom Permissions
STDIO (Claude Desktop) CLI args --permission-mode --permissions
SSE (Dify, etc.) URL Query permissionMode permissions
Streamable HTTP HTTP Header X-DB-Permission-Mode X-DB-Permissions
REST API JSON Body permissionMode permissions

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

Platform Access Method Description Guide
Cursor MCP stdio AI-powered code editor with built-in MCP support EN / 中文
Windsurf MCP stdio Codeium's AI IDE with Cascade agent EN / 中文
VS Code MCP stdio / REST API Via GitHub Copilot agent mode or Cline/Continue extensions EN / 中文
Zed MCP stdio High-performance open-source code editor EN / 中文
IntelliJ IDEA MCP stdio JetBrains IDE with MCP support (2025.1+) EN / 中文
PyCharm MCP stdio JetBrains Python IDE EN / 中文
WebStorm MCP stdio JetBrains JavaScript IDE EN / 中文
Android Studio MCP stdio Via JetBrains MCP plugin EN / 中文
Neovim MCP stdio Via MCPHub.nvim plugin EN / 中文
Emacs MCP stdio Via mcp.el package EN / 中文

AI Coding Assistants

Platform Access Method Description Guide
Claude Code MCP stdio Anthropic's agentic coding tool EN / 中文
GitHub Copilot MCP stdio Agent mode in VS Code/JetBrains EN / 中文
Cline MCP stdio / REST API Autonomous coding agent for VS Code EN / 中文
Continue MCP stdio Open-source AI code assistant EN / 中文
Roo Code MCP stdio Fork of Cline for VS Code EN / 中文
Sourcegraph Cody MCP stdio AI coding assistant EN / 中文
Amazon Q Developer MCP stdio AWS AI coding assistant EN / 中文
Devin MCP stdio AI software engineer EN / 中文
Goose MCP stdio Block's AI coding agent EN / 中文
Gemini CLI MCP stdio Google's command-line AI tool EN / 中文

Desktop AI Chat Applications

Platform Access Method Description Guide
Claude Desktop MCP stdio Anthropic's official desktop app EN / 中文
ChatGPT Desktop MCP SSE/Streamable HTTP OpenAI's desktop app with MCP connectors EN / 中文
Cherry Studio MCP stdio Multi-model desktop chat app EN / 中文
LM Studio MCP stdio Run local LLMs with MCP support EN / 中文
Jan MCP stdio Open-source ChatGPT alternative EN / 中文
Msty MCP stdio Desktop AI chat application EN / 中文
LibreChat MCP stdio Open-source chat interface EN / 中文
Witsy MCP stdio Desktop AI assistant EN / 中文
5ire MCP stdio Cross-platform AI chat EN / 中文
ChatMCP MCP stdio MCP-focused chat UI EN / 中文
HyperChat MCP stdio Multi-platform chat app EN / 中文
Tome MCP stdio macOS app for local LLMs EN / 中文

Web-Based AI Platforms

Platform Access Method Description Guide
Claude.ai MCP SSE/Streamable HTTP Anthropic's web interface EN / 中文
ChatGPT MCP SSE/Streamable HTTP Via custom connectors EN / 中文
Dify MCP SSE/Streamable HTTP LLM app development platform EN / 中文
Coze REST API ByteDance's AI bot platform EN / 中文
n8n REST API / MCP Workflow automation platform EN / 中文
Replit MCP stdio Online IDE with AI agent EN / 中文
MindPal MCP SSE/Streamable HTTP No-code AI agent builder EN / 中文

Agent Frameworks & SDKs

Platform Access Method Description Guide
LangChain MCP stdio Popular LLM framework EN / 中文
Smolagents MCP stdio Hugging Face agent library EN / 中文
OpenAI Agents SDK MCP SSE/Streamable HTTP OpenAI's agent framework EN / 中文
Amazon Bedrock Agents MCP SSE/Streamable HTTP AWS AI agent service EN / 中文
Google ADK MCP stdio Google's Agent Development Kit EN / 中文
Vercel AI SDK MCP stdio Vercel's AI development kit EN / 中文
Spring AI MCP stdio Java/Spring AI framework EN / 中文

CLI Tools & Terminal

Platform Access Method Description Guide
Claude Code CLI MCP stdio Terminal-based coding agent EN / 中文
Warp MCP stdio AI-powered terminal EN / 中文
Oterm MCP stdio Chat with Ollama via CLI EN / 中文
MCPHost MCP stdio CLI chat with LLMs EN / 中文

Productivity & Automation

Platform Access Method Description Guide
Raycast MCP stdio macOS productivity launcher EN / 中文
Notion MCP SSE/Streamable HTTP Workspace with AI integration EN / 中文
Obsidian MCP stdio Via MCP Tools plugin EN / 中文
Home Assistant MCP stdio Home automation platform EN / 中文

Messaging Platform Integrations

Platform Access Method Description Guide
Slack MCP stdio / REST API Via Slack MCP bots EN / 中文
Discord MCP stdio / REST API Via Discord MCP bots EN / 中文
Mattermost MCP stdio Open-source messaging EN / 中文

Local LLM Runners

Platform Access Method Description Guide
Ollama MCP stdio Run local LLMs EN / 中文
LM Studio MCP stdio Local LLM desktop app EN / 中文
Jan MCP stdio Offline ChatGPT alternative EN / 中文

Development & Testing Tools

Platform Access Method Description Guide
MCP Inspector MCP stdio Official MCP debugging tool EN / 中文
Postman REST API / MCP API testing platform EN / 中文

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

Deployment

Database Guides

HTTP API

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

🤝 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.

Star History Chart

📝 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>

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选