Universal DB MCP Plus

Connect AI to Your Database with Natural Language — Enhanced Fork

An enhanced fork of Anarkh-Lee/universal-db-mcp, adding multi-database configuration, SSH tunneling, connection pooling, and improved MongoDB support on top of the original universal database MCP connector.

Enhancements • Features • Quick Start • Databases • Docs • Contributing

English | 中文文档

🔀 Fork Origin & Enhancements

This project is forked from Anarkh-Lee/universal-db-mcp (upstream v2.14.0). We are grateful to the original author for building such an excellent universal database MCP connector. This fork is published on npm as universal-db-mcp-plus.

What's Different from Upstream

Category	Enhancement	Description
Multi-Database Config	`databases.json` / `databases.yaml`	Configure and manage multiple database connections in a single file, with `${ENV_VAR}` support for secrets
SSH Tunneling	SSH tunnel service	Access remote databases through SSH bastion hosts with automatic port forwarding
Connection Pooling	Pool management service	Reusable adapter pool with health checks, auto-reconnection, and graceful shutdown
MongoDB Enhancements	URI & Replica Set support	Full MongoDB connection string support, replica set through SSH tunnels, improved JSON query parsing with better error messages
Tool Descriptions	Dynamic per-database-type	MCP tool descriptions are dynamically generated based on connected database type (SQL vs MongoDB vs Redis), giving AI better context
MySQL Optimization	`BASE TABLE` filter	Restrict schema fetching to base tables only, avoiding views and system tables
MCP Verification	`scripts/verify-mcp.js`	Automated MCP stdio protocol verification script

New Files Added

src/services/config-service.ts — Multi-database configuration management
src/services/connection-pool.ts — Database adapter pool with health monitoring
src/services/ssh-tunnel.ts — SSH tunnel creation and lifecycle management
src/utils/tool-descriptions.ts — Dynamic MCP tool descriptions per database type
databases.json.example / databases.yaml.example — Example multi-database config files
scripts/verify-mcp.js — MCP protocol verification utility

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

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-plus",
        "--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-plus

# 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-plus --type mysql ...

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

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

# Full control (equivalent to --danger-allow-write)
npx universal-db-mcp-plus --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 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 this repository
git clone https://github.com/ppanphper/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 a star to both the upstream repo and this enhanced fork!

📝 Changelog

See CHANGELOG.md for a detailed version history.

🙏 Acknowledgements

This project is based on universal-db-mcp by Anarkh-Lee. We deeply appreciate the original author's work in building this comprehensive universal database MCP connector.

Original project by Anarkh-Lee · Enhanced by ppanphper

Name		Name	Last commit message	Last commit date
Latest commit History 129 Commits
.claude		.claude
.github		.github
assets		assets
config		config
docker		docker
docs		docs
scripts		scripts
serverless		serverless
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
create-claude-config.bat		create-claude-config.bat
databases.json.example		databases.json.example
databases.yaml.example		databases.yaml.example
docker-compose.yml		docker-compose.yml
fly.toml		fly.toml
package-lock.json		package-lock.json
package.json		package.json
railway.json		railway.json
render.yaml		render.yaml
tsconfig.json		tsconfig.json
universal-db-mcp-0.1.0.tgz		universal-db-mcp-0.1.0.tgz
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Universal DB MCP Plus

🔀 Fork Origin & Enhancements

What's Different from Upstream

New Files Added

Why Universal DB MCP?

✨ Features

Performance Improvements

🚀 Quick Start

Installation

MCP Mode (Claude Desktop)

HTTP API Mode

MCP SSE Mode (Dify and Remote Access)

📊 Supported Databases

🏗️ Architecture

🔒 Security

Permission Modes

🔌 Supported Platforms

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

📚 Documentation

Getting Started

Deployment

Database Guides

HTTP API

Integrations

Advanced

🤝 Contributing

📄 License

🌟 Star History

📝 Changelog

🙏 Acknowledgements

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages