Db MCP Server

🚀 DB MCP Server

DB MCP Server 是一個基於 Spring Boot 和 Spring AI 的數據庫 MCP (Model Context Protocol) 服務器。它能通過 MCP 協議為 AI 應用提供數據庫訪問能力，採用響應式編程模型，支持多種主流數據庫，可提供安全、高效的數據庫操作接口。

🚀 快速開始

環境要求

• Java 17 或更高版本
• Maven 3.6+
• 支持的數據庫之一（MySQL、PostgreSQL、Oracle、SQL Server、KingBase）

安裝步驟

1. 克隆項目

git clone https://github.com/KISS-GG/DB_MCP_Server.git
cd DB_MCP_Server

2. 構建項目

mvn clean package

3. 運行服務

# 方式一：使用 Docker 運行
sh build.sh
docker-compose up -d

# 方式二：運行 JAR 包
java -jar target/db-mcp-server-0.0.1.jar

4. 驗證服務 訪問健康檢查端點：

curl http://localhost:8888/actuator/health

MCP 客戶端配置

在 Claude Desktop 或其他 MCP 客戶端中配置：

{
  "mcpServers": {
    "db-mcp-server": {
      "url": "http://localhost:8888/mcp",
      "transport": "streamable-http"
    }
  }
}

監控端點

Spring Actuator 提供以下監控端點：

• http://localhost:8888/actuator/health - 健康檢查
• http://localhost:8888/actuator/mappings - 端點映射
• http://localhost:8888/actuator/beans - Bean 信息
• http://localhost:8888/actuator/env - 環境變量

✨ 主要特性

• 🚀 響應式架構 - 基於 Spring WebFlux 實現高性能異步通信
• 🔌 多數據庫支持 - 支持 MySQL、PostgreSQL、Oracle、SQL Server、KingBase
• 🛡️ 安全可靠 - 內置寫操作預覽和確認機制，防止誤操作
• 📊 元數據查詢 - 支持查詢表結構、索引、約束等數據庫元信息
• 🔄 事務支持 - 批量 SQL 執行支持事務，保證數據一致性
• 🎯 MCP 協議 - 標準化的 AI 工具調用接口
• 📈 監控就緒 - 集成 Spring Actuator，提供健康檢查和監控端點

💻 使用示例

基礎用法

示例 1：在 Claude Desktop 中查詢數據

用戶提問：

"幫我查詢 test_db 數據庫中 users 表裡年齡大於 25 歲的所有用戶"

AI 響應： AI 會自動調用 executeQuery 工具，執行查詢並返回結果。

示例 2：安全的寫操作流程

步驟 1：預覽寫操作

用戶: "將 id 為 1 的用戶狀態更新為 active"
AI: 調用 executeWrite，返回預覽信息和 confirmId

步驟 2：確認執行

用戶: "確認執行"
AI: 調用 confirmWrite，使用 confirmId 執行操作

示例 3：查詢表結構

用戶提問：

"查看 users 表的結構"

AI 響應： AI 調用 getMetadata 工具，返回表的完整結構信息，包括列定義、主鍵、索引等。

示例 4：批量操作

用戶提問：

"批量插入 3 條用戶記錄"

AI 響應： AI 調用 executeBatch 工具，在事務中執行多條 INSERT 語句。

📚 詳細文檔

可用工具列表

DB MCP Server 提供以下 6 個數據庫操作工具：

1. executeQuery - 執行查詢 SQL

執行 SELECT 查詢語句，返回查詢結果。 參數：

• dbType (必填): 數據庫類型 (mysql/postgresql/oracle/sqlserver/kingbase)
• host (必填): 數據庫主機地址
• port (必填): 數據庫端口
• username (必填): 用戶名
• password (必填): 密碼
• database (必填): 數據庫名
• sql (必填): SQL 查詢語句
• params (可選): SQL 參數列表
• limit (可選): 結果行數限制，默認 1000
• timeout (可選): 超時時間（秒），默認 30
• useSsl (可選): 是否使用 SSL

示例：

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "SELECT * FROM users WHERE age > ?",
  "params": [18],
  "limit": 100
}

2. executeWrite - 執行寫操作（預覽模式）

執行 INSERT/UPDATE/DELETE 操作，返回預覽信息和確認 ID。 參數：

• 基礎連接參數（同 executeQuery）
• sql (必填): SQL 寫操作語句
• params (可選): SQL 參數列表

返回：

• confirmId: 確認 ID，用於後續確認執行
• preview: 操作預覽信息

示例：

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "UPDATE users SET status = ? WHERE id = ?",
  "params": ["active", 1]
}

3. confirmWrite - 確認執行寫操作

確認並執行之前預覽的寫操作。 參數：

• confirmId (必填): executeWrite 返回的確認 ID
• timeout (可選): 超時時間（秒），默認 30

示例：

{
  "confirmId": "abc123-def456-ghi789"
}

4. executeBatch - 批量執行 SQL

在同一事務中批量執行多條 SQL 語句，失敗則全部回滾。 參數：

• 基礎連接參數（同 executeQuery）
• sqlList (必填): SQL 語句列表
• timeout (可選): 超時時間（秒），默認 30

示例：

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sqlList": [
    "INSERT INTO users (name, age) VALUES ('Alice', 25)",
    "INSERT INTO users (name, age) VALUES ('Bob', 30)",
    "UPDATE users SET status = 'active' WHERE age > 20"
  ]
}

5. getMetadata - 查詢數據庫元數據

查詢數據庫表結構、索引、約束、註釋等元信息。 參數：

• 基礎連接參數（同 executeQuery）
• tableName (可選): 表名，不填則返回所有表名

示例：

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "tableName": "users"
}

返回信息：

• 表名和註釋
• 列信息（名稱、類型、長度、是否可空、默認值、註釋）
• 主鍵信息
• 索引信息
• 外鍵約束

6. executeDDL - 執行 DDL 語句

執行 CREATE/ALTER/DROP 等 DDL 語句（危險操作需確認）。 參數：

• 基礎連接參數（同 executeQuery）
• sql (必填): DDL 語句
• confirmed (必填): 確認執行危險操作（DROP/TRUNCATE/ALTER 需設為 true）
• timeout (可選): 超時時間（秒），默認 30

示例：

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "username": "root",
  "password": "password",
  "database": "test_db",
  "sql": "CREATE TABLE test (id INT PRIMARY KEY, name VARCHAR(100))",
  "confirmed": false
}

⚠️ 重要提示

根據全局安全約束，禁止刪除數據庫的表和數據。執行 DROP/TRUNCATE/DELETE 等危險操作時需要特別謹慎。

🛠️ 技術細節

工作流程

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Server
    participant DB as Database

    AI->>MCP: HTTP POST 請求 (/mcp)
    MCP-->>AI: 返回 JSON 響應
    AI->>MCP: 發送工具調用請求
    MCP->>DB: 執行數據庫操作
    DB-->>MCP: 返回結果
    MCP-->>AI: 返回執行結果

核心組件

• MCP Server - 基於 Spring AI MCP Server Streamable HTTP 實現
• HTTP 端點 - /mcp 提供 HTTP Streaming 連接（POST 方法）
• 消息端點 - /mcp 處理 MCP 協議消息
• 工具提供者 - 通過 @Tool 註解自動註冊數據庫操作工具
• 連接池 - HikariCP 高性能數據庫連接池

技術棧

核心框架

• Spring Boot 3.5.9 - 應用框架
• Spring AI 1.1.2 - MCP Server 支持
• Spring WebFlux - 響應式 Web 框架

數據庫相關

• HikariCP - 高性能連接池
• JDBC Drivers - 多數據庫驅動支持

工具庫

• Hutool 5.8.41 - Java 工具類庫
• Lombok 1.18.42 - 簡化 Java 代碼

監控運維

• Spring Boot Actuator - 應用監控和管理

構建工具

• Maven 3.6+ - 項目構建管理
• Java 17 - 運行環境

項目結構

db-mcp-server/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── top/zymnb/dbmcpserver/
│   │   │       ├── DbMcpServerApplication.java    # 應用入口
│   │   │       ├── config/
│   │   │       │   └── McpConfig.java             # MCP 配置
│   │   │       └── service/
│   │   │           └── McpService.java            # MCP 工具服務
│   │   └── resources/
│   │       └── application.yml                     # 應用配置
├── pom.xml                                         # Maven 配置
└── README.md                                       # 本文件

🗄️ 支持的數據庫

數據庫連接示例

MySQL:

{
  "dbType": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "mydb"
}

PostgreSQL:

{
  "dbType": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "mydb"
}

Oracle:

{
  "dbType": "oracle",
  "host": "localhost",
  "port": 1521,
  "database": "ORCL"
}

❓ 常見問題

Q1: 如何配置 KingBase 數據庫驅動？

KingBase 驅動需要手動安裝到本地 Maven 倉庫：

mvn install:install-file \
  -Dfile=kingbase8-8.6.0.jar \
  -DgroupId=cn.com.kingbase \
  -DartifactId=kingbase8 \
  -Dversion=8.6.0 \
  -Dpackaging=jar

Q2: 連接數據庫時出現超時怎麼辦？

檢查以下幾點：

1. 數據庫服務是否正常運行
2. 網絡連接是否暢通
3. 防火牆是否允許連接
4. 數據庫用戶權限是否正確
5. 可以增加 timeout 參數值

Q3: 寫操作的 confirmId 有效期是多久？

confirmId 默認有效期為 5 分鐘，超時後需要重新執行 executeWrite 獲取新的 confirmId。

Q4: 支持連接池配置嗎？

支持。可以通過環境變量或配置文件調整 HikariCP 連接池參數：

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000

Q5: 如何處理大量數據查詢？

1. 使用 limit 參數限制返回行數
2. 分頁查詢大數據集
3. 考慮使用索引優化查詢性能
4. 對於超大結果集，建議導出到文件

🤝 貢獻指南

我們歡迎所有形式的貢獻！

如何貢獻

1. Fork 項目
   • 點擊右上角的 Fork 按鈕
2. 創建特性分支

git checkout -b feature/your-feature-name

3. 提交更改

git commit -m "Add: 你的功能描述"

4. 推送到分支

git push origin feature/your-feature-name

5. 創建 Pull Request
   • 在 GitHub 上創建 PR
   • 詳細描述你的更改

代碼規範

• 遵循 Java 編碼規範
• 使用 Lombok 簡化代碼
• 添加必要的註釋和文檔
• 確保所有測試通過

📄 許可證

本項目採用 MIT License 開源協議。

MIT License

Copyright (c) 2026 DB MCP Server Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 致謝

感謝以下開源項目和技術：

• Spring Boot - 強大的 Java 應用框架
• Spring AI - AI 應用開發框架
• MCP Protocol - 模型上下文協議
• HikariCP - 高性能連接池
• Hutool - Java 工具類庫

特別感謝所有貢獻者和使用者的支持！

⭐ Star History

如果這個項目對你有幫助，請給我們一個 Star！