内容
# MCP 多数据库连接器
[](https://python.org)
[](https://github.com/)
[](LICENSE)
MCP（模型上下文协议）多数据库连接器模板，支持 Microsoft SQL Server 与 PostgreSQL。通过静态 Schema 预载与智能分析，让 AI 精确理解您的数据库结构与业务逻辑。
使用 `schemas_config/` 目录自定义您的业务领域配置。
---
```text
┌─────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌──────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │Claude Desktop│ │ Web 浏览器│ │ 第三方应用程序 │ │
│ └──────┬───────┘ └────┬─────┘ └───────┬───────┘ │
└─────────┼───────────────┼────────────────┼──────────┘
│ │ │
┌─────────┼───────────────┼────────────────┼──────────┐
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ MCP Server │ │ HTTP API Server │ │
│ │ (stdio) │ │ (FastAPI + OpenAPI) │ │
│ └──────┬───────┘ └───────────┬─────────────┘ │
│ │ 服务层 │ │
└─────────┼──────────────────────┼────────────────────┘
│ │
┌─────────┼──────────────────────┼────────────────────┐
│ ▼ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ 统一工具处理层 (Tools) │ │
│ │ db_query / db_schema / db_dependencies ... │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ 核心层 │
│ ┌──────────┐ ┌────────┴────────┐ ┌────────────┐ │
│ │ 配置管理 │ │ 数据库管理器 │ │ 错误处理 │ │
│ │ (Config) │ │(DatabaseManager)│ │(Exceptions)│ │
│ └──────────┘ └────────┬────────┘ └────────────┘ │
└─────────────────────────┼───────────────────────────┘
│
┌─────────────────────────┼────────────────────────────┐
│ ▼ │
│ ┌──────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Schema 缓存 │ │Schema │ │ 静态 Schema │ │
│ │(LFU+LRU+TTL) │ │ 内省器 │ │ 加载器(JSON) │ │
│ └──────────────┘ └────┬─────┘ └───────┬───────┘ │
│ 数据层 │ │ │
│ ┌─────────────┼────────────────┤ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ SQL Server │ │ PostgreSQL │ │schemas_config/│ │
│ │ (MSSQL) │ │ │ │ JSON 配置文件 │ │
│ └────────────┘ └────────────┘ └───────────────┘ │
└──────────────────────────────────────────────────────┘
```
---
## 核心功能
### 基础能力
- **多数据库支持**：原生 SQL Server 与 PostgreSQL 连接器
- **10+ 数据库工具**：查询、Schema 分析、依赖关系分析、导出等
- **静态 Schema 预载**：通过 JSON 配置注入业务语义
- **智能缓存**：LFU+LRU+TTL 多层缓存，毫秒级响应
- **关联分析**：表格依赖与外键关系分析
### AI 增强
- **Schema 感知 AI**：根据实际数据库结构与业务语义产生精确 SQL
- **Token 优化**：Schema 压缩节省 60-80% Token 用量
- **SQL 语法导引**：自动检测数据库类型，提供对应语法提示
### 双模式架构
- **Claude Desktop (MCP 协议)**：通过 stdio 提供完整 MCP 工具支持
- **Open WebUI (HTTP API)**：RESTful API + OpenAPI/Swagger 文档
---
## 快速开始
### 方式一：Claude Desktop (MCP 协议)
**1. 准备环境**
```bash
git clone https://github.com/Bright0505/MCP_DB.git
cd MCP_DB
cp .env.example .env
# 编辑 .env 填入数据库连接信息
```
**2. 配置 Claude Desktop**
找到配置文件：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- Linux：`~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mcp-db": {
"command": "python",
"args": ["-m", "server"],
"cwd": "/path/to/MCP_DB/src",
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_NAME": "your_database",
"DB_USER": "your_username",
"DB_PASSWORD": "your_password",
"DB_PORT": "5432",
"SCHEMA_ENABLE_CACHE": "true"
}
}
}
}
```
**3. 重启 Claude Desktop 并测试**
```bash
请测试数据库连接状态
```
### 方式二：HTTP API (Open WebUI)
```bash
# Docker 部署（推荐）
cp .env.example .env
# 编辑 .env
docker-compose up -d
# 或本地执行
pip install -e .
python -m http_server
```
访问 API 文档：http://localhost:8000/docs
### 使用范例
```bash
# 测试连接
curl -X POST http://localhost:8000/api/test-connection
# 执行查询
curl -X POST http://localhost:8000/api/query \
-H "Content-Type: application/json" \
-d '{"query": "SELECT TOP 10 * FROM ORDERS"}'
# 查看表格 Schema
curl -X POST http://localhost:8000/api/schema \
-H "Content-Type: application/json" \
-d '{"table_name": "ORDERS"}'
```
---
## 环境配置
```bash
# 数据库类型
DB_TYPE=postgresql # 或 mssql
# 数据库连接
DB_HOST=localhost
DB_NAME=your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_PORT=5432 # PostgreSQL: 5432, SQL Server: 1433
# Schema 缓存（建议启用）
SCHEMA_ENABLE_CACHE=true
SCHEMA_CACHE_TTL_MINUTES=60
# HTTP API
HTTP_HOST=0.0.0.0
HTTP_PORT=8000
```
---
## MCP 工具一览
| 工具名称 | 说明 |
|----------|------|
| `db_query` | 执行 SELECT 查询（只读模式） |
| `db_schema` | 查看表格结构与字段信息 |
| `db_schema_summary` | 数据库对象摘要统计 |
| `db_dependencies` | 分析表格依赖关系 |
| `db_test_connection` | 测试数据库连接 |
| `db_cache_stats` | 查看缓存统计 |
| `db_cache_invalidate` | 清除缓存 |
| `db_schema_reload` | 重新加载 Schema 配置 |
| `db_static_schema_info` | 查看静态 Schema 信息 |
| `db_export_schema` | 导出表格 Schema |
| `db_syntax_guide` | SQL 语法参考指南 |
---
## 业务定制化
本项目是一个**模板**，通过 `schemas_config/` 目录进行定制化：
### 三层知识注入架构
```bash
schemas_config/
├── tables_list.json # 表格白名单与全局设置
├── global_patterns.json # 全局字段命名模式（如 _ID$、_DATE$、_AMT$）
├── ai_enhancement.json # AI 查询增强（关键字对应、查询模板）
├── tables/ # 个别表格详细配置
│ └── ORDERS.json # 字段说明、状态值定义、JOIN 建议
└── examples/
└── sample_table.json # 完整范例参考
```
### 定制化步骤
1. 在 `schemas_config/tables_list.json` 注册您的表格
2. 为重要表格建立 `schemas_config/tables/<TABLE>.json` 详细配置
3. 在 `schemas_config/ai_enhancement.json` 配置 AI 查询模式
4. 参考 `schemas_config/examples/sample_table.json` 获取完整范例
详细指南：[schemas_config/README.md](schemas_config/README.md) | [完整配置手册](schemas_config/SCHEMA_CONFIG_GUIDE.md)
---
## 文档导航
### 入门
- [MCP 快速入门](docs/MCP_QUICK_START.md) — MCP 功能完整指南（推荐）
- [快速开始](docs/quick-start.md) — 5 分钟上手指南
- [安装指南](docs/installation.md) — 环境设置与安装步骤
### 技术
- [系统架构](docs/architecture.md) — 分层架构设计与模块说明
- [Schema 系统](docs/schema-system.md) — 静态 Schema 与 JSON 配置
- [性能优化](docs/performance.md) — 缓存系统与 Token 优化
### 开发
- [开发环境](docs/development/README.md) — 开发历史与贡献指南
- [测试指南](docs/testing.md) — 单元测试与覆盖率
- [Claude Code 设置](docs/CLAUDE.md) — Claude Code hooks 与自动化
---
## 授权
MIT License — 詳見 [LICENSE](LICENSE)
---
**版本**：v1.0.0
**最后更新**：2026-01-27
