Db MCP Server

🚀 DB MCP Server

DB MCP Serverは、Spring BootとSpring AIをベースにした、データベースのMCP（Model Context Protocol）サーバーです。このサーバーは、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. サービスを起動する

# 方法1：Dockerで起動
sh build.sh
docker-compose up -d

# 方法2：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を統合し、ヘルスチェックと監視エンドポイントを提供します。

ワークフロー

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高性能データベース接続プールを使用しています。

💻 使用例

例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"
}

返却情報：

• テーブル名とコメント
• 列情報（名前、タイプ、長さ、NULL許容、デフォルト値、コメント）
• 主キー情報
• インデックス情報
• 外部キー制約

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などの危険な操作を実行する場合は、特に注意が必要です。

🗄️ サポートされるデータベース

データベース接続の例

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"
}

🔧 技術詳細

コアフレームワーク

• 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                                       # このファイル

❓ よくある質問

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履歴

このプロジェクトが役に立った場合は、Starをしていただけると幸いです！