# ai_mcp: Multi-DB MCP Server

一个可直接部署的多数据库 MCP 服务，支持 PostgreSQL / ClickHouse / MySQL。仓库结构和体验目标参考 `mysql_mcp_server`：

- 一次拉取即可使用
- `.env` 配置驱动
- 既支持 MCP stdio，也支持 HTTP API 调用

---

## 目录

- `db_mcp_service/server.py`: MCP stdio 工具（`list_databases` / `list_tables` / `describe_table` / `execute_sql`）
- `db_mcp_service/api.py`: FastAPI 对外 HTTP 接口
- `db_mcp_service/run_api.py`: HTTP 启动入口
- `requirements.txt`: 运行依赖
- `pyproject.toml`: 可选的包安装元信息（含命令入口）
- `start-mcp.ps1/.cmd`, `start-api.ps1/.cmd`: 一键启动脚本
- `Dockerfile`, `docker-compose.yml`: 一键容器启动
- `examples/claude-desktop.json`: Claude Desktop 配置示例

---

## 第一步：拉取并准备环境

```bash
git clone <your-repo-url>
cd ai_mcp
python -m venv .venv
. .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

## 第二步：配置

```bash
copy .env.example .env
```

编辑 `.env`，只开启需要的后端，例如只开 PostgreSQL：

```env
POSTGRES_ENABLED=true
POSTGRES_DSN=postgresql://user:password@127.0.0.1:5432/postgres

CLICKHOUSE_ENABLED=false
MYSQL_ENABLED=false
```

---

## 启动方式（两条主线）

### 1) MCP stdio（推荐给 MCP 客户端）

```bash
# 推荐直接用项目内脚本
./start-mcp.ps1

# 或直接运行模块
python -m db_mcp_service
```

### 2) HTTP API（给第三方系统调用）

```bash
./start-api.ps1
# 或
python -m db_mcp_service.run_api
```

HTTP 默认监听：`0.0.0.0:8000`，可在 `.env` 中改：

- `DB_MCP_API_HOST`
- `DB_MCP_API_PORT`
- `DB_MCP_API_RELOAD`

---

## 可选：安装成全局命令

如果你的环境可以安装 build 依赖，可执行：

```bash
python -m pip install -e .
```

安装后可直接使用：

- `db-mcp`（MCP stdio）
- `db-mcp-api`（FastAPI）

如果该方式不可用，直接用上面的 `python -m` 启动方式即可。两者行为一致。

---

## HTTP API 路由

- `GET /health`
- `GET /databases`
- `GET /databases/{database}`
- `GET /databases/{database}/tables?schema=public`
- `GET /databases/{database}/tables/{table}?schema=public`
- `POST /sql`

`POST /sql` 示例：

```json
{
  "database": "postgres",
  "sql": "SELECT 1",
  "params": null,
  "allow_write": false
}
```

默认只读。`allow_write=true` 或设置全局 `MCP_ALLOW_WRITE=true` 后才能执行写语句。

---

## API 鉴权（可选）

`.env` 配置：

```env
DB_MCP_API_TOKEN=your-token
```

设置后访问 `/sql` 需要携带 Header：`X-API-Key: your-token`。

---

## Docker 启动（可直接给别人用）

```bash
docker compose up --build
```


---

## 直接可复用的 Claude Desktop 配置

见文件：[`examples/claude-desktop.json`](examples/claude-desktop.json)

你可以把它复制到 Claude Desktop 的配置中，仅需改数据库连接字段即可直接共享。