# MCP DB Server

> 让 AI Agent 通过自然语言查询数据库的 MCP 服务器

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 构建，提供只读数据库查询能力。支持自动 Schema 发现、SQL 查询执行、安全校验。

## 项目结构

```
mcp-db-server/
├── src/
│   ├── server.py     # MCP 服务入口 + 4 个工具
│   ├── db.py         # 数据库连接 + Schema 发现
│   └── safety.py     # SQL 安全校验（只读模式）
├── sample.db         # 示例 SQLite 数据库
├── .env              # 数据库连接配置
├── .env.example      # 配置模板
├── requirements.txt  # 依赖
├── setup_sample_db.py# 创建示例数据库
└── test_server.py    # 测试脚本
```

## 快速开始

### ⚡ 选择你的终端

根据你用的终端，Python 命令写法不同：

| 终端 | 命令 |
|------|------|
| **Git Bash**（Claude Code 默认） | `/d/anaconda/python` |
| **PowerShell** | `D:\anaconda\python.exe` |
| **cmd** | `D:\anaconda\python.exe` |

以下所有命令以 Git Bash 为例，换成你的终端对应写法即可。

### 1. 安装依赖

```bash
pip install mcp python-dotenv
```

### 2. 配置数据库

编辑 `.env` 文件：

```ini
DATABASE_URL=sqlite:///sample.db
```

当前支持 SQLite。示例数据库包含 `departments` 和 `employees` 两张表。

### 3. 启动服务

```bash
# Git Bash:
/d/anaconda/python -m src.server
# PowerShell/cmd:
D:\anaconda\python.exe -m src.server
```

### 4. 用 MCP Inspector 调试（推荐）

```bash
# Git Bash:
/d/anaconda/Scripts/mcp dev src/server.py
# PowerShell/cmd:
D:\anaconda\Scripts\mcp.exe dev src/server.py
```

这会启动一个 Web 调试界面（`http://localhost:5173`），在浏览器中测试所有工具。

### 5. 集成到 Claude Desktop

在 Claude Desktop 的配置 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "mcp-db-server": {
      "command": "D:\\anaconda\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\Users\\86150\\source\\repos\\mcp-db-server"
    }
  }
}
```

## 可用工具

| 工具 | 参数 | 说明 |
|------|------|------|
| `list_tables` | 无 | 列出所有表名 |
| `get_schema` | `table: string` | 查看指定表的结构 |
| `describe_db` | 无 | 查看完整数据库结构概览 |
| `query` | `sql: string` | 执行 SELECT 查询 |

## 安全特性

- **只读模式**：仅允许 SELECT 语句，拦截 INSERT/UPDATE/DELETE/DROP 等
- **CTE 支持**：允许 `WITH ... SELECT` 复杂查询
- **错误提示**：被拦截时会给出明确原因

## 测试验证

```bash
# Git Bash:
/d/anaconda/python test_server.py
# PowerShell/cmd:
D:\anaconda\python.exe test_server.py
```

## 简历项目描述

> **Database MCP Server** — 基于 Model Context Protocol 构建的数据库查询代理服务器
>
> - 设计并实现了 MCP 协议服务端，提供 4 个标准化工具接口供 AI Agent 调用
> - 实现自动 Schema 发现，支持动态获取表结构和字段信息
> - 构建只读 SQL 安全校验层，防止 DDL/DML 操作，确保数据安全
> - 支持 SQLite，架构可扩展至 MySQL/PostgreSQL
> - 集成 Claude Desktop，实现自然语言驱动的数据库查询