Universal DB MCP
้็จๆฐๆฎๅบ MCP ่ฟๆฅๅจ๏ผๆฏๆ MySQLใPostgreSQLใOracleใMongoDB ็ญ 17 ็งๆฐๆฎๅบ๏ผๆฏๆ Claude DesktopใCursorใWindsurfใVS CodeใChatGPT ็ญ 50+ ๅนณๅฐ๏ผ็จ่ช็ถ่ฏญ่จๆฅ่ฏขๅๅๆๆฐๆฎ
Installation
npx universal-db-mcpAsk AI about Universal DB MCP
Powered by Claude ยท Grounded in docs
I know everything about Universal DB MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Universal DB MCP
Connect AI to Your Database with Natural Language
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.
Features โข Quick Start โข Databases โข Docs โข Contributing
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, REPLACEupdate- UPDATEdelete- DELETE, TRUNCATEddl- 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
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.
๐ Changelog
See CHANGELOG.md for a detailed version history.
Made with โค๏ธ by Anarkh-Lee
