Universal DB MCP

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

English | 中文文档

______________________________________________________________________

为什么选择通用DB MCP？

想象一下，问你的人工智能助手： *“按订单价值显示本月前10名客户”* 从数据库中获取即时结果，无需编写SQL。通用数据库MCP通过模型上下文协议（MCP）和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%)      │
└─────────────────────────────────────┘

✨ 特性

• 17数据库支持 -MySQL、PostgreSQL、Redis、Oracle、SQL Server、MongoDB、SQLite和10个中国国内数据库
• 55+平台集成 -适用于Claude Desktop、Cursor、VS Code、ChatGPT、Dify和 50+其他平台
• 灵活的架构 -2种启动模式（stdio:http），4种访问方式：MCP stdio、MCP SSE、MCP Streamable http和REST API
• 安全第一 -默认情况下，只读模式可防止意外修改数据
• 智能高速缓存 -具有可配置TTL的模式缓存，可实现超快性能
• 批量查询优化 -大型数据库的模式检索速度提高了100倍
• 架构增强 -表注释，隐式关系推理，以提高Text2SQL的准确性
• 多模式支持 -自动发现所有用户模式（PostgreSQL、SQL Server、Oracle、DM等）
• 数据屏蔽 -自动敏感数据保护（电话、电子邮件、身份证、银行卡等）
• 连接稳定性 -连接池、TCP保持活动以及长时间运行会话的自动重新连接

性能改进

🚀 快速开始

安装

npm install -g universal-db-mcp

MCP模式（克劳德桌面）

添加到您的Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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"
      ]
    }
  }
}

重新启动Claude Desktop并开始提问：

• *“显示用户表的结构”*
• *“统计过去7天的订单”*
• *“按销售额查找前5名产品”*

HTTP API模式

# 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模式（Dify和远程访问）

在HTTP模式下运行时，服务器还通过SSE（服务器发送事件）和Streamable HTTP公开MCP协议端点。这允许像Dify这样的平台直接使用MCP协议进行连接。

SSE端点（传统）：

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

流式HTTP端点（MCP 2025规范，推荐）：

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

看 Dify集成指南 有关详细的设置说明。

📊 支持的数据库

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────────────┐
│                         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)           │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🔒 安全

默认情况下，Universal DB MCP在中运行 只读模式，阻止所有写入操作（INSERT、UPDATE、DELETE、DROP等）。

权限模式

支持细粒度权限控制以实现灵活配置：

权限类型：

• read -SELECT查询（始终包含在内）
• insert -插入、替换
• update -更新
• delete -删除、截断
• ddl -创建、更改、删除、重命名

使用示例：

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

按传输方式配置权限：

⚠️ 不同的传输使用不同的参数命名约定！

最佳实践：

• 从不在生产环境中启用写入模式
• 使用专用只读数据库帐户
• 通过VPN或堡垒主机连接
• 定期审核查询日志

🔌 支持的平台

Universal DB MCP可与任何支持MCP协议或REST API的平台配合使用。以下是一个全面的列表：

AI驱动的代码编辑器和IDE

AI编码助理

桌面AI聊天应用程序

基于网络的人工智能平台

代理框架和SDK

CLI工具和终端

生产力和自动化

消息传递平台集成

当地LLM跑步者

开发和测试工具

备注：任何兼容MCP的客户端都可以通过stdio（本地）或SSE/Streamable HTTP（远程）连接。任何HTTP客户端都可以使用REST API。

📚 文档

入门指南

• 安装指南
• 快速开始
• 配置
• 使用示例

部署

• 部署概述
• 本地部署
• 云部署

数据库指南

• 数据库支持概述
• MySQL
• PostgreSQL
• 更多数据库。..

HTTP API

• API 参考
• 部署指南

集成

AI编辑器和IDE： 光标 | VS Code | 捷凯 | 帆板运动 | 泽德 | 尼奥夫 | Emacs

人工智能助理： 克劳德桌面版 | 克劳德代码 | | 克莱恩 | 继续

人工智能平台： 迪菲 | 扣子 | n8n | ChatGPT | LangChain

桌面应用程序： 樱桃工作室 | LM 工作室 | 一月 | 奥拉玛

消息： Slack | Discord 的中文翻译是“不和谐”或“纷争”。

工具： MCP检查员 | 邮递员

📁 查看全部55个集成指南 | 中文版本请在对应文档名后加 .zh-CN

高级

• 安全指南
• 多租户指南
• 建筑
• 故障排除

🤝 贡献

欢迎投稿！请阅读我们的 贡献指南 在提交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

📄 许可证

该项目根据 MIT许可证.

🌟 星史

如果你觉得这个项目有用，请考虑给它一颗星！您的支持有助于我们继续改进Universal DB MCP。

📝 更新日志

看 更改日志.md 查看详细的版本历史。

______________________________________________________________________

Made with ❤️ by Anarkh-Lee