# DatabaseMcp

**Repository Path**: cj5035123/database-mcp

## Basic Information

- **Project Name**: DatabaseMcp
- **Description**: DatabaseMcp 是一个 MCP（Model Context Protocol）服务器，使 AI 代理能够与多种关系数据库交互。支持 MySQL、PostgreSQL、SQL Server、Oracle 四种主流数据库。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-19
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DatabaseMcp

DatabaseMcp 是一个 MCP（Model Context Protocol）服务器，使 AI 代理能够与多种关系数据库交互。支持 MySQL、PostgreSQL、SQL Server、Oracle 四种主流数据库。

## 技术栈

- **后端**: ASP.NET Core 8
- **前端**: Vue 3 + Element Plus
- **元数据存储**: SQLite

## 支持的数据库

- MySQL
- PostgreSQL
- SQL Server
- Oracle

## 部署方式

### 方式一：Docker Compose（推荐）

```bash
# 克隆项目
git clone https://gitee.com/cj5035123/database-mcp.git
cd database-mcp

# 编辑 docker-compose.yml，修改 Jwt__Key 为随机密钥
# （使用 openssl rand -hex 32 生成 64 位十六进制字符串）

# 启动服务
docker compose -f deploy/docker-compose.yml up -d

# 查看日志
docker compose -f deploy/docker-compose.yml logs -f

# 停止服务
docker compose -f deploy/docker-compose.yml down
```

服务默认运行在 `http://localhost:15035`。

### 方式二：下载发布包部署（推荐）

从 [Releases](https://gitee.com/cj5035123/database-mcp/releases) 页面下载最新版本的 `publish.zip`，解压后可直接运行或注册为 Windows 服务。

```bash
# 1. 解压发布包到目标目录
#    手动解压，或用 PowerShell：
#    Expand-Archive -Path publish.zip -DestinationPath C:\apps\databasemcp

# 2. 编辑 appsettings.json，配置 Jwt:Key（至少 32 位随机字符串）

# 3. 直接运行（前台模式，用于测试）
C:\apps\databasemcp\DatabaseMcp.Server.exe

# 4. 或注册为 Windows 服务（生产环境，开机自启）
sc.exe create "DatabaseMcp" binPath="C:\apps\databasemcp\DatabaseMcp.Server.exe" start=auto

# 5. 启动服务
sc.exe start DatabaseMcp

# 6. 查看服务状态
sc.exe query DatabaseMcp
```

> 使用 PowerShell 注册服务：
> ```powershell
> Expand-Archive -Path publish.zip -DestinationPath C:\apps\databasemcp
> New-Service -Name DatabaseMcp -BinaryPathName "C:\apps\databasemcp\DatabaseMcp.Server.exe" -StartupType Automatic
> Start-Service DatabaseMcp
> ```

发布包为独立可执行文件，无需安装 .NET 运行时。服务以 `LocalSystem` 账户在后台运行，可在 `appsettings.json` 中配置 `Kestrel:Endpoints:Http:Url` 修改监听地址和端口（默认 `http://0.0.0.0:15035`）。

### 方式三：手动构建发布（前后端打包成单一项目）

```bash
# 1. 构建前端，输出到 wwwroot 目录
cd src/DatabaseMcp.Web
npm install
npm run build

# 2. 发布后端（自动包含前端静态文件）
cd ../..
dotnet publish src/DatabaseMcp.Server/DatabaseMcp.Server.csproj -c Release -o publish

# 3. 运行（单进程同时提供 API 和前端页面）
cd publish
dotnet DatabaseMcp.Server.dll
```

> 前端构建产物（`dist/`）会被复制到后端的 `wwwroot/` 目录，.NET 运行时自动托管静态文件。非 API 路由（非 `/api`、非 `/mcp`）统一回退到 `index.html`，由 Vue Router 处理。**只需启动一个 .NET 进程**。

### 方式四：开发模式运行

```bash
# 运行后端（自动启动 Vite 前端开发服务器）
dotnet run --project src/DatabaseMcp.Server/DatabaseMcp.Server.csproj

# 或分别启动（后端端口 15035，前端端口 5173）
dotnet run --project src/DatabaseMcp.Server/DatabaseMcp.Server.csproj
cd src/DatabaseMcp.Web && npm run dev
```

## MCP 客户端注册方法

DatabaseMcp 支持 MCP Streamable HTTP 协议，通过 HTTP 端点暴露工具。

> **注意**：每个用户注册后系统会生成唯一的 **API Key**。在 Web 管理页面的"API Key"或"个人信息"页面可以查看和重置 Key。重置后旧 Key 立即失效。

### Claude Desktop

编辑 Claude Desktop 配置文件 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "databasemcp": {
      "url": "http://localhost:15035/mcp",
      "headers": {
        "Authorization": "Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

> **注意**：Claude Desktop 连接的是 HTTP 地址（`http://localhost:15035/mcp`），**无需** `/message` 后缀。

### VS Code（Cline / Roo Code / Continue 等插件）

以 Cline 为例，在 MCP Server 配置中添加：

```json
{
  "mcpServers": {
    "databasemcp": {
      "type": "http",
      "url": "http://localhost:15035/mcp/message",
      "headers": {
        "Authorization": "Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

> **注意**：VS Code 插件使用 Streamable HTTP 协议，指向 `/mcp/message` 端点。

### 直接调用（curl）

```bash
# 初始化
curl -X POST http://localhost:15035/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# 列出工具
curl -X POST http://localhost:15035/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 执行只读查询
curl -X POST http://localhost:15035/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{
      "name":"query_sql",
      "arguments":{
        "project":"项目名称",
        "environment":"Test",
        "sql":"SELECT * FROM users LIMIT 10"
      }
    }
  }'

# 执行 DML 操作
curl -X POST http://localhost:15035/mcp/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "jsonrpc":"2.0","id":4,"method":"tools/call",
    "params":{
      "name":"execute_dml",
      "arguments":{
        "project":"项目名称",
        "environment":"Test",
        "sql":"UPDATE users SET status=1 WHERE id=1"
      }
    }
  }'
```

## 暴露的 MCP 工具

| 工具名 | 说明 | 允许的 SQL |
|---|---|---|
| `query_sql` | 执行只读 SQL 查询 | SELECT / WITH / SHOW / DESCRIBE / EXPLAIN |
| `execute_dml` | 执行数据操作语句 | INSERT / UPDATE / DELETE / MERGE（必须带 WHERE 子句） |

## 环境说明

DatabaseMcp 支持两种环境配置，在创建/编辑项目时选择：

- **Test** — 测试环境，适合开发和调试
- **Production** — 生产环境，建议使用独立的数据库实例

## 配置参考

| 配置键 | 默认值 | 说明 |
|---|---|---|
| `Jwt:Key` | 必填（至少 32 字符） | JWT 签名密钥 |
| `ConnectionStrings:MetaDb` | `databasemcp.db` | SQLite 元数据库路径 |
| `Mcp:RateLimitPerMinute` | 60 | MCP 调用每分钟最大次数 |
| `SqlSecurity:MaxRowsDefault` | 1000 | 查询返回的最大行数 |
| `ConnectionPool:MaxConnectionsPerInstance` | 20 | 每个数据库实例最大并发连接数 |
| `AuditLog:RetentionDays` | 90 | 审计日志保留天数 |
| `DataProtection:KeyDirectory` | （内存） | 数据保护密钥持久化目录 |

## 功能特性

- 通过 MCP Streamable HTTP 协议暴露 `query_sql`（只读查询）和 `execute_dml`（数据操作）两个工具
- 基于 JWT 的用户认证和 MCP API Key 鉴权（HMAC-SHA256 前缀哈希）
- 连接池管理（支持按实例限制并发连接数）
- SQL 验证与安全过滤（自动区分只读查询和 DML 操作，DML 必须带 WHERE 子句）
- 审计日志记录（SQL 执行记录、耗时、影响行数）
- 数据库连接健康检查
- 支持 Web 管理界面（项目配置、连接测试、审计日志查看、MCP 配置查看）

## 许可证

MIT

## 参考

本项目参考 [apisql-dev/apisql-mcp](https://github.com/apisql-dev/apisql-mcp) 的设计理念实现。