# DB Query MCP 🗄️

让 Claude / AI 助手直接查询 SQLite 数据库。安全只读模式，开箱即用。

## 功能

### Tool（工具）

| 工具 | 说明 |
|------|------|
| `query(sql, db_path)` | 执行 SELECT 查询，返回表格化结果 |
| `list_tables(db_path)` | 列出数据库中所有表和视图 |
| `describe_table(table, db_path)` | 查看表结构：字段名、类型、约束、行数 |

### Resource（资源）

| 资源 URI | 说明 |
|----------|------|
| `db://schema` | 完整数据库 Schema（所有表 + 列 + 行数） |
| `db://settings` | 安全配置：只读模式、行数上限、超时等 |

## 安全设计

| 机制 | 说明 |
|------|------|
| 🔒 默认只读 | 仅允许 SELECT / WITH / EXPLAIN / DESCRIBE / PRAGMA |
| 🚫 危险拦截 | DROP / TRUNCATE / ALTER 无条件拦截 |
| 📏 行数上限 | 单次最多 1000 行，防止输出爆炸 |
| ⏱️ 超时保护 | 查询超时 10 秒自动断开 |

## 为什么有用？

- 产品经理对 AI 说「查一下上周注册的用户数」——无需打开数据库客户端
- 开发对 AI 说「users 表有哪些字段」——即时获取表结构
- 数据分析师对 AI 说「统计各地区的订单量和金额」——AI 直接写 SQL 查询

## 快速开始

### 环境要求

- Python 3.10+
- [fastmcp](https://github.com/jlowin/fastmcp) >= 3.0

### 安装

```bash
# 克隆仓库
git clone https://github.com/rubber25ba/db-query-mcp.git
cd db-query-mcp

# 安装依赖
pip install fastmcp
```

### 运行

```bash
python server.py
```

## 在 Claude Code 中配置

```json
{
  "mcpServers": {
    "db-query": {
      "command": "python",
      "args": ["C:/Users/YOUR_USER/path/to/db-query-mcp/server.py"]
    }
  }
}
```

配置后对 Claude 说：

- 「查一下 /data/app.db 里有哪些表」
- 「在 /data/app.db 上执行 SELECT * FROM users LIMIT 10」
- 「帮我看 orders 表的结构」

## 使用示例

### 示例 1：探索数据库

```
用户：/data/business.db 里面有什么表？

Claude → list_tables(db_path="/data/business.db")
→ 返回所有表名和视图名
```

### 示例 2：查询数据

```
用户：统计过去 30 天各品类销售额，用 business.db

Claude → query(
  sql="SELECT category, SUM(amount) as total FROM orders WHERE created_at > date('now', '-30 days') GROUP BY category ORDER BY total DESC",
  db_path="/data/business.db"
)
→ 返回表格化结果
```

### 示例 3：查看表结构

```
用户：users 表有哪些字段？

Claude → describe_table(table_name="users", db_path="/data/business.db")
→ 返回字段名、类型、非空约束、默认值、行数
```

## 支持场景

| 场景 | 适用 |
|------|------|
| 本地 SQLite 数据库查询 | ✅ |
| 产品/运营自助查数据 | ✅ |
| 开发调试（快速看库） | ✅ |
| MySQL 数据库 | 🔜 开发中 |

## 技术栈

- Python + sqlite3（内置）
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP Server 框架
- [MCP](https://modelcontextprotocol.io/) — Anthropic 开源协议

## 定制开发

需要对接 MySQL / PostgreSQL？想把内部数据库集成到 AI 助手？欢迎提 issue 或联系定制：

- ✉️ GitHub Issue: [提交需求](https://github.com/rubber25ba/db-query-mcp/issues)
- 📋 也承接：企业 API MCP、自动化工作流 MCP、多数据源统一查询 MCP

---

*Built for real business use.*