mysql-mcp-server

mysql-mcp-server

한국어 README.md

0. 実行

Docker での実行

データベース接続情報は必要に応じて変更してください。

docker run -d --name mcp-mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=mcpTest1234!!! \
  -e MYSQL_DATABASE=mcp_test \
  -e MCP_PORT=8081 \
  -p 3306:3306 mineru/mcp-mysql:1.0.0

Docker Compose での実行

事前に設定された構成で進めます。

docker-compose up -d

Python で直接実行する場合

pip install -r requirements.txt
python mysql_mcp_server/main.py run

Cursor の設定

MCP 機能は Cursor バージョン 0.46 以降で利用できます。

また、MCP 機能は Cursor Pro アカウントのユーザーのみが利用できます。

ツール追加のヒント

• ツールの追加
  • execute 関数は実際のロジック実行 (Service Layer) を行います。
  • @tool デコレーターは、ツールを MCP に登録するのに役立ちます (Controller Layer)。
• 説明
  • mysql_mcp_server/executors 配下の各ファイルは、1 つのツールを表します。
  • 新しいツールを追加した場合は、mysql_mcp_server/executors/__init__.py にインポートし、__all__ 配列に含める必要があります。
  • これにより、モジュールが TOOLS_DEFINITION 変数に自動的に登録されます。

flowchart LR;
    A[AI Model] -->|Request tool list| B[MCP Server]
    B -->|Return available tools| A

    A -->|Request specific tool execution| B
    B -->|Call the corresponding executor| C[Executors]
    
    subgraph Executors
        C1[execute_create_table] -->|Create table| D
        C2[execute_desc_table] -->|View table schema| D
        C3[execute_explain] -->|Query execution plan| D
        C4[execute_insert_query] -->|Execute INSERT query| D
        C5[execute_insight_starter] -->|Checking the schema for building reports| D
        C6[execute_invoke_viz_pro] -->|Visualization chart recommendations| D
        C7[execute_select_query] -->|Execute SELECT query| D
        C8[execute_show_tables] -->|Retrieve table list| D
    end

    D[DatabaseManager] -->|Connect to MySQL| E[MySQL 8.0]

    E -->|Return results| D
    D -->|Send results| C
    C -->|Return results| B
    B -->|Return execution results| A

🚧 開発ロードマップ 🚧

• ⚙️ パラメーターオプション

  • 🔧 ツールごとの有効/無効スイッチ: 入力コンテキストのコストを削減する機能を提供します 💰
  • 🔒 クエリのセキュリティレベル設定: DROP、DELETE、UPDATE など、資産価値を損なう可能性のある機能に対してオプションの制御を提供します 🚫

• ✨ 機能

  • 📊 データ分析レポート: ユーザーのリクエストに基づいて各種チャートを適切に選択できるよう、モデルに最適化されたレポート生成機能を提供します 📈
    • 📝 規定フォームのレポート機能
    • 🖌️ レポートテンプレートの多様化
  • 🗄️ Text2SQL サポートの拡張
  • 🌐 SSH 接続サポート: 高度な操作のために SSH 経由のセキュアなリモートアクセスを可能にします 🔑
  • 📥 ファイル抽出機能
    • 📄 CSV
    • 📑 JSON
    • 📉 Excel

1. 概要

MCP MySQL Server は、MCP (Model Context Protocol) に基づく MySQL データベース操作用のサーバーアプリケーションです。このサーバーは、AI モデルが MySQL データベースと対話できるようにするツールを提供します。

2. システム構成

2.1 主要コンポーネント

• MCP サーバー: AI モデルと通信する FastMCP サーバー
• MySQL データベース: データを管理および保存します
• ツール: データベース操作を実行するエグゼキューター

2.2 技術スタック

• 言語: Python
• データベース: MySQL 8.0
• 主要ライブラリ:
  • mcp: AI 通信のために Model Context Protocol を実装します
  • PyMySQL: MySQL に接続し、クエリを実行します
  • pandas: データを処理および分析します
  • python-dotenv: 環境変数を管理します
  • fire: コマンドラインインターフェースを実装します

2.3 デプロイ環境

• Docker および Docker Compose によるコンテナ化デプロイ
• ポート: 8081 (MCP サーバー)、3306 (MySQL)

3. ディレクトリ構造

MCPBoilerPlate/
├── mysql_mcp_server/           # Main application directory
│   ├── executors/              # Database operation executors
│   │   ├── create_table.py     # Tool for creating tables
│   │   ├── desc_table.py       # Tool for viewing table schema
│   │   ├── explain.py          # Tool for query execution plans
│   │   ├── insert_query.py     # Tool for INSERT query execution
│   │   ├── insight_starter.py  # Schema verification tools for write reports
│   │   ├── invoke_viz_pro.py   # Tool for Visualization chart recommendation
│   │   ├── select_query.py     # Tool for SELECT query execution
│   │   └── show_tables.py      # Tool for retrieving table lists
│   ├── helper/                 # Utility modules
│   │   ├── db_conn_helper.py   # Manages database connections
│   │   ├── logger_helper.py    # Logging utilities
│   │   └── tool_decorator.py   # Tool decorator
│   └── main.py                 # Application entry point
├── docker-compose.yml          # Docker Compose configuration
├── Dockerfile                  # Docker image build settings
├── requirements.txt            # Dependency package list
└── .env.example                # Example environment variables file

4. アーキテクチャ設計

4.1 レイヤー構造

1. インターフェース層: MCP サーバー (FastMCP)
2. ビジネスロジック層: ハンドラーとエグゼキューター
3. データアクセス層: データベース接続とクエリ実行

4.2 主要クラスとモジュール

• MySQLMCPServer: MCP サーバーを初期化して実行するメインサーバークラス
• DatabaseManager: シングルトンパターンベースのデータベース接続マネージャー
• Executors: データベース操作用ツールのコレクション
  • execute_create_table: テーブルを作成します
  • execute_desc_table: テーブルスキーマを確認します
  • execute_explain: クエリの実行プランを提供します
  • execute_insert_query: INSETR クエリを実行します
  • execute_select_query: SELECT クエリを実行します
  • execute_show_tables: テーブル一覧を取得します

4.3 通信フロー

1. AI モデルが MCP サーバーから利用可能なツールの一覧を要求します。
2. サーバーが利用可能なツール一覧を返します。
3. AI モデルが特定のツールの実行を要求します。
4. サーバーが対応するエグゼキューターを呼び出し、データベース操作を実行します。
5. 実行結果が AI モデルに返されます。

5. 拡張性とメンテナンス

• ツールの追加: executors ディレクトリに新しいツールを実装し、__init__.py に登録します。
• 環境設定: 環境変数は .env ファイルで管理します。
• ログ記録: logger_helper を使用して、一貫したログ記録を確保します。

6. デプロイと実行

6.1 ローカルでの実行

# Setup environment
cp .env.example .env
# Modify .env file as needed

# Install dependencies
pip install -r requirements.txt

# Run the server
python mysql_mcp_server/main.py run

6.2 Docker デプロイ

# Start database using Docker Compose
docker-compose up -d db
# Build and run mysql-mcp-server with Docker Compose (including rebuilds)
docker-compose up -d --build mysql-mcp-server

7. セキュリティに関する考慮事項

• データベースの認証情報は環境変数で管理します。
• 本番環境では強力なパスワードを使用します。
• 必要に応じて、データベース接続に SSL/TLS 暗号化の実装を検討します。