Universal DB MCP

用自然语言将AI连接到您的数据库

一个实现模型上下文协议（MCP）和HTTP API的通用数据库连接器，使AI助手能够使用自然语言查询和分析您的数据库。与Claude Desktop、Cursor、Windsurf、VS Code、ChatGPT等50多个平台兼容。

功能 • 快速入门 • 支持的数据库 • 文档 • 贡献

English | 中文文档

---

为什么选择Universal DB MCP？

想象一下，您可以这样问您的AI助手：“本月按订单金额排名前10位的客户有哪些？”然后立即从您的数据库中获取结果——无需编写SQL语句。Universal DB MCP通过模型上下文协议（MCP）和HTTP API，将AI助手与您的数据库无缝连接，从而实现这一功能。

您：“过去30天内注册用户的平均订单金额是多少？”

AI：让我为您查询一下……

┌─────────────────────────────────────┐
│ 平均订单金额：$127.45        │
│ 新用户总数：1,247              │
│ 有订单的用户：892人（71.5%）      │
└─────────────────────────────────────┘

✨ 功能

• 支持17种数据库 - MySQL、PostgreSQL、Redis、Oracle、SQL Server、MongoDB、SQLite以及10种中国国产数据库
• 集成55+个平台 - 兼容Claude Desktop、Cursor、VS Code、ChatGPT、Dify等50多个平台
• 灵活的架构 - 支持两种启动模式（stdio/http），提供四种访问方式：MCP stdio、MCP SSE、MCP可流式HTTP和REST API
• 安全优先 - 默认为只读模式，防止意外修改数据
• 智能缓存 - 模式缓存并可配置TTL，实现超快性能
• 批量查询优化 - 大型数据库的模式检索速度提升高达100倍
• 模式增强 - 表注释、隐式关系推断，提高Text2SQL准确性
• 多模式支持 - 自动发现所有用户模式（PostgreSQL、SQL Server、Oracle、达梦等）
• 数据脱敏 - 自动保护敏感数据（电话、邮箱、身份证、银行卡等）
• 连接稳定性 - 连接池、TCP Keep-Alive以及长会话自动重连机制

性能提升

表数量	优化前	优化后	提升
50张表	~5秒	~200毫秒	快25倍
100张表	~10秒	~300毫秒	快33倍
500张表	~50秒	~500毫秒	快100倍

🚀 快速入门

安装

npm install -g universal-db-mcp

MCP模式（Claude Desktop）

将以下内容添加到您的Claude Desktop配置文件中：

• 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"
      ]
    }
  }
}

重启Claude Desktop，即可开始提问：

• “给我看看users表的结构”
• “统计最近7天内的订单数”
• “找出销量前5名的产品”

HTTP API模式

# 设置环境变量
export MODE=http
export HTTP_PORT=3000
export API_KEYS=your-secret-key

# 启动服务器
npx universal-db-mcp

# 测试API
curl http://localhost:3000/api/health

MCP SSE模式（Dify及远程访问）

在HTTP模式下运行时，服务器还会通过SSE（服务器发送事件）和可流式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请求

端点	方法	描述
/sse	GET	建立SSE连接（旧版）
/sse/message	POST	向SSE会话发送消息
/mcp	POST	可流式HTTP端点（推荐）
/mcp	GET	用于可流式HTTP的SSE流
/mcp	DELETE	关闭会话

详细设置请参阅Dify集成指南。

📊 支持的数据库

数据库	类型	默认端口	分类
MySQL	mysql	3306	开源
PostgreSQL	postgres	5432	开源
Redis	redis	6379	NoSQL
Oracle	oracle	1521	商业
SQL Server	sqlserver	1433	商业
MongoDB	mongodb	27017	NoSQL
SQLite	sqlite	-	嵌入式
达梦	dm	5236	中文
KingbaseES	kingbase	54321	中文
GaussDB	gaussdb	5432	中文（华为）
OceanBase	oceanbase	2881	中文（蚂蚁集团）
TiDB	tidb	4000	分布式
ClickHouse	clickhouse	8123	OLAP
PolarDB	polardb	3306	云服务（阿里巴巴）
Vastbase	vastbase	5432	中文
HighGo	highgo	5866	中文
GoldenDB	goldendb	3306	中文（中兴通讯）

🏗️ 架构

┌─────────────────────────────────────────────────────────────────────────┐
│                         通用数据库 MCP                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  启动模式：                                                          │
│  ┌────────────────────────────┬────────────────────────────────────┐    │
│  │ 标准输入输出模式                 │ HTTP 模式                          │    │
│  │ (npm run start:mcp)        │ (npm run start:http)               │    │
│  └─────────────┬──────────────┴───────────────┬────────────────────┘    │
│                │                              │                          │
│                ▼                              ▼                          │
│  ┌─────────────────────────┐    ┌───────────────────────────────────┐   │
│  │      MCP 协议       │    │           HTTP 服务器             │   │
│  │    (stdio 传输)    │    │                                   │   │
│  │                         │    │  ┌─────────────────────────────┐  │   │
│  │  工具：                 │    │  │      MCP 协议           │  │   │
│  │  • execute_query        │    │  │  (SSE / 流式 HTTP)    │  │   │
│  │  • get_schema           │    │  │                             │  │   │
│  │  • get_table_info       │    │  │  工具：(与 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_sample_data      │    │  │  • connect_database         │  │   │
│  │  • get_connection_status│    │  │  • disconnect_database      │  │   │
│  │                         │    │  │  • get_connection_status    │  │   │
│  │  对于：Claude Desktop,   │    │  │                             │  │   │
│  │       Cursor, 等等.      │    │  │                             │  │   │
│  └─────────────┬───────────┘    │  │                             │  │   │
│                │                │  └──────────────┬──────────────┘  │   │
│                │                │                 │                 │   │
│                │                │  ┌──────────────┴──────────────┐  │   │
│                │                │  │        REST API             │  │   │
│                │                │  │                             │  │   │
│                │                │  │  端点：                 │  │   │
│                │                │  │  • /api/connect             │  │   │
│                │                │  │  • /api/query               │  │   │
│                │                │  │  • /api/schema              │  │   │
│                │                │  │  • ... (10+ 端点)      │  │   │
│                │                │  │                             │  │   │
│                │                │  │  对于：Coze, n8n, 自定义     │  │   │
│                │                │  └──────────────┬──────────────┘  │   │
│                │                └─────────────────┼─────────────────┘   │
│                │                                  │                     │
│                └──────────────────┬───────────────┘                     │
│                                   ▼                                     │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     核心业务逻辑                           │  │
│  │  • 查询执行    • 模式缓存                           │  │
│  │  • 安全验证    • 连接管理                    │  │
│  └──────────────────────────────────┬───────────────────────────────┘  │
│                                     ▼                                   │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                    数据库适配层                         │  │
│  │  MySQL │ PostgreSQL │ Redis │ Oracle │ MongoDB │ SQLite │ ...    │  │
│  │        (连接池 + TCP Keep-Alive + 自动重试)           │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🔒 安全性

默认情况下，通用数据库 MCP 以 只读模式 运行，阻止所有写操作（INSERT、UPDATE、DELETE、DROP 等）。

权限模式

支持细粒度的权限控制，可灵活配置：

模式	允许的操作	描述
safe（默认）	SELECT	只读，最安全
readwrite	SELECT、INSERT、UPDATE	读/写但无删除
full	所有操作	完全控制（危险！）
custom	自定义组合	通过 --permissions 指定

权限类型：

• read - SELECT 查询（始终包含）
• insert - INSERT、REPLACE
• update - UPDATE
• delete - DELETE、TRUNCATE
• ddl - CREATE、ALTER、DROP、RENAME

使用示例：

# 只读模式（默认）
npx universal-db-mcp --type mysql ...

# 读/写但无删除
npx universal-db-mcp --type mysql --permission-mode readwrite ...

# 自定义：仅读和插入
npx universal-db-mcp --type mysql --permissions read,insert ...

# 全部控制（等同于 --danger-allow-write）
npx universal-db-mcp --type mysql --permission-mode full ...

按传输方式配置权限：

⚠️ 不同传输方式使用不同的参数命名规范！

传输方式	参数位置	权限模式	自定义权限
STDIO（Claude Desktop）	CLI 参数	--permission-mode	--permissions
SSE（Dify 等）	URL 查询	permissionMode	permissions
流式 HTTP	HTTP 头	X-DB-Permission-Mode	X-DB-Permissions
REST API	JSON 请求体	permissionMode	permissions

最佳实践：

• 生产环境中切勿启用写入模式
• 使用专用的只读数据库账号
• 通过 VPN 或堡垒主机进行连接
• 定期审计查询日志

🔌 支持的平台

通用数据库 MCP 可与任何支持 MCP 协议或 REST API 的平台配合使用。以下是完整列表：

基于 AI 的代码编辑器与 IDE

平台	访问方式	描述	指南
Cursor	MCP stdio	具有内置 MCP 支持的 AI 驱动代码编辑器	EN / 中文
Windsurf	MCP stdio	Codeium 的 AI IDE，配备 Cascade 代理	EN / 中文
VS Code	MCP stdio / REST API	通过 GitHub Copilot 代理模式或 Cline/Continue 扩展	EN / 中文
Zed	MCP stdio	高性能开源代码编辑器	EN / 中文
IntelliJ IDEA	MCP stdio	JetBrains IDE，支持 MCP（2025.1 及以上版本）	EN / 中文
PyCharm	MCP stdio	JetBrains 的 Python IDE	EN / 中文
WebStorm	MCP stdio	JetBrains 的 JavaScript IDE	EN / 中文
Android Studio	MCP stdio	通过 JetBrains 的 MCP 插件	EN / 中文
Neovim	MCP stdio	通过 MCPHub.nvim 插件	EN / 中文
Emacs	MCP stdio	通过 mcp.el 包	EN / 中文

AI 编程助手

平台	访问方式	描述	指南
Claude Code	MCP stdio	Anthropic 的代理式编程工具	EN / 中文
GitHub Copilot	MCP stdio	VS Code/JetBrains 中的代理模式	EN / 中文
Cline	MCP stdio / REST API	适用于 VS Code 的自主编程代理	EN / 中文
Continue	MCP stdio	开源 AI 代码助手	EN / 中文
Roo Code	MCP stdio	Cline 的 VS Code 分支	EN / 中文
Sourcegraph Cody	MCP stdio	AI 编程助手	EN / 中文
Amazon Q Developer	MCP stdio	AWS 的 AI 编程助手	EN / 中文
Devin	MCP stdio	AI 软件工程师	EN / 中文
Goose	MCP stdio	Block 的 AI 编程代理	EN / 中文
Gemini CLI	MCP stdio	Google 的命令行 AI 工具	EN / 中文

桌面 AI 聊天应用

平台	访问方式	描述	指南
Claude Desktop	MCP stdio	Anthropic 官方桌面应用	EN / 中文
ChatGPT Desktop	MCP SSE/Streamable HTTP	OpenAI 的桌面应用，配备 MCP 连接器	EN / 中文
Cherry Studio	MCP stdio	多模型桌面聊天应用	EN / 中文
LM Studio	MCP stdio	在本地运行 LLM，并支持 MCP	EN / 中文
Jan	MCP stdio	开源的 ChatGPT 替代品	EN / 中文
Msty	MCP stdio	桌面 AI 聊天应用	EN / 中文
LibreChat	MCP stdio	开源聊天界面	EN / 中文
Witsy	MCP stdio	桌面 AI 助手	EN / 中文
5ire	MCP stdio	跨平台 AI 聊天	EN / 中文
ChatMCP	MCP stdio	专注于 MCP 的聊天 UI	EN / 中文
HyperChat	MCP stdio	多平台聊天应用	EN / 中文
Tome	MCP stdio	用于本地 LLM 的 macOS 应用	EN / 中文

基于Web的AI平台

平台	访问方式	描述	指南
Claude.ai	MCP SSE/可流式HTTP	Anthropic的网页界面	EN / 中文
ChatGPT	MCP SSE/可流式HTTP	通过自定义连接器	EN / 中文
Dify	MCP SSE/可流式HTTP	LLM应用开发平台	EN / 中文
Coze	REST API	字节跳动的AI机器人平台	EN / 中文
n8n	REST API / MCP	工作流自动化平台	EN / 中文
Replit	MCP stdio	带有AI代理的在线IDE	EN / 中文
MindPal	MCP SSE/可流式HTTP	无代码AI代理构建工具	EN / 中文

代理框架与SDK

平台	访问方式	描述	指南
LangChain	MCP stdio	流行的LLM框架	EN / 中文
Smolagents	MCP stdio	Hugging Face代理库	EN / 中文
OpenAI Agents SDK	MCP SSE/可流式HTTP	OpenAI的代理框架	EN / 中文
Amazon Bedrock Agents	MCP SSE/可流式HTTP	AWS AI代理服务	EN / 中文
Google ADK	MCP stdio	Google的代理开发工具包	EN / 中文
Vercel AI SDK	MCP stdio	Vercel的AI开发工具包	EN / 中文
Spring AI	MCP stdio	Java/Spring AI框架	EN / 中文

CLI工具与终端

平台	访问方式	描述	指南
Claude Code CLI	MCP stdio	基于终端的编码代理	EN / 中文
Warp	MCP stdio	AI驱动的终端	EN / 中文
Oterm	MCP stdio	通过CLI与Ollama聊天	EN / 中文
MCPHost	MCP stdio	通过CLI与LLM对话	EN / 中文

生产力与自动化

平台	访问方式	描述	指南
Raycast	MCP stdio	macOS生产力启动器	EN / 中文
Notion	MCP SSE/可流式HTTP	带有AI集成的工作空间	EN / 中文
Obsidian	MCP stdio	通过MCP Tools插件	EN / 中文
Home Assistant	MCP stdio	家庭自动化平台	EN / 中文

消息平台集成

平台	访问方式	描述	指南
Slack	MCP stdio / REST API	通过Slack MCP机器人	EN / 中文
Discord	MCP stdio / REST API	通过Discord MCP机器人	EN / 中文
Mattermost	MCP stdio	开源消息平台	EN / 中文

本地LLM运行工具

平台	访问方式	描述	指南
Ollama	MCP stdio	运行本地LLM	EN / 中文
LM Studio	MCP stdio	本地LLM桌面应用	EN / 中文
Jan	MCP stdio	离线版ChatGPT替代品	EN / 中文

开发与测试工具

平台	访问方式	描述	指南
MCP Inspector	MCP stdio	官方MCP调试工具	EN / 中文
Postman	REST API / MCP	API测试平台	EN / 中文

注意: 任何兼容MCP的客户端都可以通过stdio（本地）或SSE/可流式HTTP（远程）进行连接。任何HTTP客户端都可以使用REST API。

📚 文档

入门

• 安装指南
• 快速入门
• 配置
• 使用示例

部署

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

数据库指南

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

HTTP API

• API 参考
• 部署指南

集成

AI 编辑器与 IDE： Cursor | VS Code | JetBrains | Windsurf | Zed | Neovim | Emacs

AI 助手： Claude Desktop | Claude Code | GitHub Copilot | Cline | Continue

AI 平台： Dify | Coze | n8n | ChatGPT | LangChain

桌面应用： Cherry Studio | LM Studio | Jan | Ollama

消息工具： Slack | Discord

工具： MCP Inspector | Postman

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

高级

• 安全指南
• 多租户指南
• 架构
• 故障排除

🤝 贡献

我们欢迎任何贡献！请在提交 Pull Request 之前阅读我们的 贡献指南。

# 克隆仓库
git clone https://github.com/Anarkh-Lee/universal-db-mcp.git

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

📄 许可证

本项目采用 MIT 许可证 开源。

🌟 星标历史

如果您觉得这个项目很有用，请考虑给它点个星！您的支持将帮助我们持续改进 Universal DB MCP。

📝 更改日志

详细的版本历史请参阅 CHANGELOG.md。

---

由 Anarkh-Lee 用心打造 ❤️

Universal DB MCP 快速上手指南

Universal DB MCP 是一个基于模型上下文协议（MCP）和 HTTP API 的通用数据库连接器。它允许 AI 助手（如 Claude Desktop、Cursor、Dify 等）通过自然语言直接查询和分析您的数据库，无需编写 SQL。支持 MySQL、PostgreSQL、Oracle 及达梦、OceanBase 等 17 种国内外主流数据库。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本需 >= 20.0.0。
  • 检查版本：node -v
  • 下载地址：Node.js 官网 或使用国内镜像源安装。
• npm: Node.js 包管理器（随 Node.js 自动安装）。
• 数据库访问权限: 确保您拥有目标数据库的主机地址、端口、用户名、密码及数据库名称。
• AI 客户端: 已安装支持 MCP 的客户端（如 Claude Desktop、Cursor、VS Code 等）或需要 HTTP 接口的平台（如 Dify）。

提示：国内开发者若遇到 npm 安装缓慢，可临时切换至淘宝镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

使用 npm 全局安装 universal-db-mcp：

npm install -g universal-db-mcp

安装完成后，可通过以下命令验证安装是否成功：

npx universal-db-mcp --help

基本使用

Universal DB MCP 提供两种主要运行模式：MCP 模式（用于本地 AI 编辑器/桌面端）和 HTTP API 模式（用于远程服务或低代码平台）。

模式一：MCP 模式（推荐用于 Claude Desktop / Cursor）

此模式允许您在本地 AI 工具中直接通过自然语言对话操作数据库。

1. 配置客户端 找到并编辑您的 AI 客户端配置文件。

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Cursor/VS Code: 在对应的 MCP 设置界面中添加以下配置。

2. 添加服务器配置 将以下内容添加到配置文件的 mcpServers 对象中（以 MySQL 为例）：

   {
     "mcpServers": {
       "my-database": {
         "command": "npx",
         "args": [
           "universal-db-mcp",
           "--type", "mysql",
           "--host", "localhost",
           "--port", "3306",
           "--user", "root",
           "--password", "your_password",
           "--database", "your_database"
         ]
       }
     }
   }
   

   请将 your_password 和 your_database 替换为实际信息。如需连接其他数据库（如 PostgreSQL、达梦等），修改 --type 参数即可。

3. 开始使用 重启 AI 客户端，然后在对话框中输入自然语言指令，例如：

   • "显示 users 表的结构"
   • "统计过去 7 天的订单数量"
   • "找出销售额最高的前 5 个产品"

模式二：HTTP API 模式（推荐用于 Dify / 远程调用）

此模式启动一个 HTTP 服务器，提供 REST API 和 MCP over SSE/Streamable HTTP 接口。

1. 设置环境变量 在终端中设置运行模式、端口及 API 密钥：

   # Linux/Mac
   export MODE=http
   export HTTP_PORT=3000
   export API_KEYS=your-secret-key
   
   # Windows (PowerShell)
   $env:MODE="http"
   $env:HTTP_PORT="3000"
   $env:API_KEYS="your-secret-key"
   

2. 启动服务 运行以下命令启动服务器：

   npx universal-db-mcp
   

3. 测试连接 使用 curl 测试服务是否正常运行：

   curl http://localhost:3000/api/health
   

4. 集成示例

   • Dify 等平台: 使用 SSE 端点 http://localhost:3000/sse?type=mysql&host=... 或推荐的 Streamable HTTP 端点 POST http://localhost:3000/mcp 进行连接。
   • 自定义开发: 直接调用 /api/query 或 /api/schema 等 REST 接口。

安全提示：默认情况下，Universal DB MCP 运行在 只读模式 (safe)，禁止执行 INSERT、UPDATE、DELETE 等写操作以保护数据安全。如需写入权限，请在启动参数中显式配置 --permissions。