# Database MCP Server

多数据库 MCP 服务器，支持 **Oracle**、**OceanBase**（Oracle 模式 + MySQL 模式）和 **DolphinDB**。

通过 MCP 协议（stdio 传输）与 Claude Desktop 等客户端通信，提供 SQL 查询、元数据查看和 Sequence 管理能力。

## 环境要求

- **Python >= 3.10**（项目自带 venv，通过 `uv` 管理）
- 目标数据库可达（本机或网络）

## 快速开始

### 1. 安装依赖

项目使用 `uv` 管理 Python 环境和依赖：

```bash
# 安装 uv（如果没有）
pip install uv

# 创建虚拟环境并安装依赖（已安装则跳过）
uv venv --python 3.11
uv pip install -r requirements.txt

# 如果用 DolphinDB，额外安装
uv pip install dolphindb
```

### 2. 配置数据库连接

复制配置示例文件并修改：

```bash
cp db_config.example.json db_config.json
```

配置文件按环境（dev / uat / pro）组织，每个环境可以配置多个数据库连接：

```json
{
  "dev": {
    "oracle_dev": {
      "type": "oracle",
      "host": "192.168.1.10",
      "port": 1521,
      "service_name": "DEVPDB",
      "user": "dev_user",
      "password": "dev_pass"
    },
    "ob_mysql": {
      "type": "oceanbase_mysql",
      "host": "192.168.1.11",
      "port": 2883,
      "database": "test",
      "user": "root@obmysql",
      "password": ""
    }
  },
  "uat": {
    "oracle_dev": {
      "type": "oracle",
      "host": "192.168.2.10",
      "port": 1521,
      "service_name": "UATPDB",
      "user": "uat_user",
      "password": "${UAT_ORACLE_PWD}"
    }
  }
}
```

**连接类型说明**：

| type | 说明 | 必需参数 |
|------|------|---------|
| `oracle` | Oracle 或 OceanBase Oracle 模式 | host, port, service_name, user, password |
| `oceanbase_mysql` | OceanBase MySQL 模式 | host, port, user, password, database |
| `dolphindb` | DolphinDB | host, port, user, password |

> 密码支持通过 `${VAR_NAME}` 从环境变量读取，避免明文存储。

### 3. 选择运行环境

通过 `DB_ENV` 环境变量切换（默认 `dev`）：

```bash
# Windows CMD
set DB_ENV=uat

# PowerShell
$env:DB_ENV="uat"

# Bash
export DB_ENV=pro
```

## 启动服务器

```bash
# 方式一
uv run python main.py

# 方式二
uv run python -m server
```

服务器启动后会通过 **stdio** 等待 MCP 客户端连接，没有网络端口暴露。

## 注册到 Claude Desktop

在 Claude Desktop 配置文件（`claude_desktop_config.json`）中添加：

```json
{
  "mcpServers": {
    "db": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "E:/python/workspace/mcp-server-databases",
        "python",
        "-m",
        "server"
      ],
      "env": {
        "DB_ENV": "dev",
        "DB_CONFIG_PATH": "E:/python/workspace/mcp-server-databases/db_config.json"
      }
    }
  }
}
```

如需同时连接多个环境，注册多个 server：

```json
{
  "mcpServers": {
    "db-dev": {
      "command": "uv",
      "args": ["run", "--directory", "E:/...", "python", "-m", "server"],
      "env": { "DB_ENV": "dev" }
    },
    "db-pro": {
      "command": "uv",
      "args": ["run", "--directory", "E:/...", "python", "-m", "server"],
      "env": { "DB_ENV": "pro" }
    }
  }
}
```

## 注册到 OpenCode

在项目根目录创建 `opencode.json`（或编辑全局配置 `~/.config/opencode/opencode.jsonc`），添加 MCP 服务器配置：

```json
{
  "mcp": {
    "db": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--directory",
        "E:/python/workspace/mcp-server-databases",
        "python",
        "-m",
        "server"
      ],
      "enabled": true,
      "environment": {
        "DB_ENV": "dev",
        "DB_CONFIG_PATH": "E:/python/workspace/mcp-server-databases/db_config.json"
      }
    }
  }
}
```

如需同时连接多个环境，添加多个 server：

```json
{
  "mcp": {
    "db-dev": {
      "type": "local",
      "command": ["uv", "run", "--directory", "E:/...", "python", "-m", "server"],
      "enabled": true,
      "environment": { "DB_ENV": "dev" }
    },
    "db-pro": {
      "type": "local",
      "command": ["uv", "run", "--directory", "E:/...", "python", "-m", "server"],
      "enabled": false,
      "environment": { "DB_ENV": "pro" }
    }
  }
}
```

> `"enabled": false` 的 server 不会随 OpenCode 启动，需要时手动启用。

### OpenCode 与 Claude Desktop 格式对比

| 项目 | OpenCode | Claude Desktop |
|------|----------|----------------|
| 配置文件名 | `opencode.json` / `opencode.jsonc` | `claude_desktop_config.json` |
| 顶层键 | `"mcp"` | `"mcpServers"` |
| 类型字段 | `"type": "local"` | 无（默认 stdio） |
| 命令格式 | `"command": [列表]` | `"command"` + `"args"` 分开 |
| 环境变量 | `"environment"` | `"env"` |
| 启用开关 | `"enabled"` | 无 |

## 工具说明

所有工具都接受 `connection` 参数指定用哪个数据库连接，省略则使用第一个配置的连接。

| 工具 | 参数 | 说明 |
|------|------|------|
| `query` | `connection`, `sql` | 执行 SELECT 查询，返回 Markdown 表格 |
| `execute` | `connection`, `sql` | 执行 INSERT/UPDATE/DELETE/DDL |
| `list_schemas` | `connection` | 列出所有 Schema / 数据库 |
| `list_tables` | `connection`, `schema` | 列出指定 Schema 下的表 |
| `describe_table` | `connection`, `table_name`, `schema` | 查看表结构（列名、类型、可空、主键） |
| `list_sequences` | `connection`, `schema` | 列出所有 Sequence（仅 Oracle） |
| `get_sequence_value` | `connection`, `sequence_name`, `schema` | 获取 Sequence 当前值 |
| `alter_sequence` | `connection`, `sequence_name`, `schema`, `increment_by`, `min_value`, `max_value`, `cycle`, `cache`, `order_flag` | 修改 Sequence 属性 |
| `set_sequence_value` | `connection`, `sequence_name`, `value`, `schema` | 将 Sequence 设为指定值 |

## 安全

- **`execute` 工具**：可通过环境变量 `DENY_EXECUTE=true` 禁用写操作
- **数据库侧权限**：连接配置使用什么数据库账号就有什么权限，建议生产环境使用只读账号
- **密码保护**：使用 `${VAR_NAME}` 引用环境变量，密码不写入配置文件
- **无网络端口**：纯 stdio 通信，不暴露网络服务

## 配置参考

### 所有环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DB_CONFIG_PATH` | `./db_config.json` | 配置文件路径 |
| `DB_ENV` | `dev` | 运行环境（dev/uat/pro） |
| `DENY_EXECUTE` | `false` | 设为 `true` 禁用写入操作 |

### 项目依赖

| 包 | 版本要求 | 用途 |
|----|---------|------|
| mcp | >=1.0.0 | MCP Python SDK |
| oracledb | >=2.0.0 | Oracle / OceanBase Oracle 驱动 |
| pymysql | >=1.0.0 | OceanBase MySQL 驱动 |
| dolphindb | >=1.0.0（可选） | DolphinDB 驱动 |
| cryptography | >=42.0.0 | oracledb 加密依赖 |