SmartDB MCP

智能数据库查询 MCP 服务，支持在 AI 编程工具（如 Trae、Claude Desktop）中用自然语言查询数据库。

功能特性

🔌 MCP 协议：标准 stdio 传输，直接集成到 Trae / Claude Desktop 等 AI 工具
🌐 Web 管理后台：浏览器配置数据库连接，无需改配置文件
🛡️ 安全控制：密码加密存储，增删改需单独授权，查询自动限制 100 行
🗄️ 多数据库支持：达梦 (DM)、GBase 8a、GBase 8c
📦 单文件分发：打包成单个 EXE，拷贝即用

📥 直接下载

Windows 用户可直接下载打包好的 EXE，无需安装 Python 环境：

🔗 smart-db-mcp.exe (v1.0.0)

两种使用方式：

方式一：直接配到 MCP 里用

在 Trae / Claude Desktop 的 MCP 配置中指向 EXE 即可启用：

{
  "mcpServers": {
    "smart-db-mcp": {
      "command": "C:\\path\\to\\smart-db-mcp.exe",
      "args": []
    }
  }
}

配置后如需管理数据库连接，浏览器打开 http://127.0.0.1:8765 进入后台。

方式二：双击运行

下载后双击 EXE 即可启动 MCP + Web 管理后台，浏览器自动打开后台页面。

快速开始

安装依赖

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

# 达梦数据库驱动（vendor 目录已提供，离线安装即可）
pip install vendor/dmpython-2.5.32-cp311-cp311-win_amd64.whl vendor/dmsqlalchemy-2.0.12-py3-none-any.whl

达梦驱动仅支持 Windows x64 + Python 3.11，其他平台请从达梦官方获取对应版本。

启动服务

# 默认模式：MCP + Web 后台同时启动
python run.py

# 仅启动 Web 管理后台
python run.py --web

# 仅启动 MCP 服务（无 Web 后台）
python run.py --no-web

配置到 Trae

在 Trae 的 MCP 配置中添加：

{
  "mcpServers": {
    "smart-db-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\run.py"]
    }
  }
}

或使用打包好的 EXE：

{
  "mcpServers": {
    "smart-db-mcp": {
      "command": "C:\\path\\to\\smart-db-mcp.exe",
      "args": []
    }
  }
}

配置数据库

启动服务后，浏览器打开 http://127.0.0.1:8765
点击「新增数据库」，填写连接信息
点击「启用」激活 MCP 查询目标
在 AI 对话中即可用自然语言查询

打包 EXE

pip install pyinstaller -i https://mirrors.aliyun.com/pypi/simple/
python -m PyInstaller smart-db-mcp.spec --noconfirm

打包产物在 dist/smart-db-mcp.exe，单文件可直接分发。

智能体提示词

为了让 AI 更好地使用 MCP 工具，建议在智能体中配置以下提示词：

你是一个专业的数据库查询助手，擅长根据用户的自然语言需求生成准确的 SQL 语句。你可以通过 MCP 工具访问数据库元数据来辅助生成 SQL。

## 工作流程

当用户提出数据查询需求时，按以下步骤操作：

### 第一步：了解数据库结构
调用 `get_table_list` 获取所有表列表，了解有哪些表可用。根据用户提到的业务关键词（如"合同"、"凭证"、"资产"等）匹配表名或表注释，锁定相关表。

### 第二步：查看表字段详情
对锁定的表调用 `get_table_ddl`，获取完整的字段结构、类型和业务注释。重点关注：
- 字段名和业务含义
- 字段类型（VARCHAR/NUMBER/DATE 等）
- 主键字段
- 注释中的枚举值说明

### 第三步：确认枚举值（如需要）
如果 WHERE 条件涉及状态、类型等字段，且 DDL 注释中未明确枚举值，调用 `get_column_enum` 查询该字段的实际取值范围，避免猜测错误。

### 第四步：查看样例数据（如需要）
如果对字段含义仍有疑问，调用 `get_table_simple_data` 查看前 3 行数据，帮助理解数据格式和内容。

### 第五步：生成 SQL
根据以上信息生成 SQL，并调用 `verify_sql` 校验语法正确性。如果校验失败，根据错误信息修正后重新校验。

### 第六步：执行查询
SQL 校验通过后，调用 `execute_sql` 执行查询，将结果以清晰的表格或列表形式呈现给用户。

## 重要规则

1. **永远不要猜测字段名或枚举值**，必须先查 DDL 和枚举再生成 SQL
2. **表名必须带 OWNER 前缀**，格式为 `OWNER.TABLE_NAME`（如 `DEV.ai_task_result`），从 `get_table_list` 返回的 owner 和 table_name 拼接
3. **SELECT 语句会自动限制 100 行**，无需手动加 LIMIT，除非需要更少的数据
4. **INSERT/UPDATE/DELETE 需要用户明确确认后才能执行**，且需页面已授权增删改，未授权时告知用户去管理页面开启
5. 生成 SQL 时优先使用注释中明确的枚举值作为 WHERE 条件
6. 涉及多表关联时，先分别查 DDL 确认关联字段
7. 如果用户需求模糊，主动追问澄清，不要自行假设
8. 查询结果为空时，建议用户检查筛选条件或查看样例数据确认数据内容

## 输出格式

- 列出查询结果
- 对查询结果做简要分析说明

项目结构

├── run.py              # 统一入口（MCP + Web）
├── mcp_server.py       # MCP 服务（stdio）
├── main.py             # Web 管理后台（FastAPI）
├── config.py           # 配置（路径解析）
├── database.py         # SQLite 配置库
├── db_connector.py     # 数据库连接引擎
├── dm_tool.py          # 达梦数据库工具函数
├── crypto.py           # 密码加密/解密
├── static/
│   └── index.html      # Web 管理页面
├── requirements.txt    # Python 依赖
├── smart-db-mcp.spec   # PyInstaller 打包配置
└── LICENSE             # MIT 许可证

MCP 工具列表

| 工具 | 说明 | |------|------| | get_table_list | 获取数据库中所有表列表（含 owner、表名、注释） | | get_table_ddl | 获取指定表的字段结构（含字段名、类型、业务注释） | | get_column_enum | 获取指定字段的枚举/字典值（最多30条） | | get_table_simple_data | 获取指定表的前3行样例数据 | | verify_sql | 校验 SQL 语法正确性 | | execute_sql | 执行 SQL 语句（查询自动限制100行） |

支持的数据库

| 数据库 | 类型标识 | 默认端口 | |--------|----------|----------| | 达梦 (DM) | dm | 5236 | | GBase 8a | gbase_8a | 5258 | | GBase 8c | gbase_8c | 5432 |

License

MIT

MCP Servers