MCP Server for MySQL based on NodeJS

NodeJS ベースの MySQL 用 MCP サーバー

MySQL データベースへのアクセスを提供する Model Context Protocol サーバーです。このサーバーにより、LLM はデータベースのスキーマを調査し、SQL クエリを実行できます。

目次

• 要件
• インストール
  • Claude Desktop
  • Cursor
  • Smithery
  • MCP Get
  • ローカルリポジトリからのクローン
• コンポーネント
• 設定
• 環境変数
• マルチ DB モード
• スキーマ固有の権限
• テスト
• トラブルシューティング
• コントリビューション
• ライセンス

要件

• Node.js v18 以降
• MySQL 5.7 以降（MySQL 8.0 以降を推奨）
• 必要な操作に応じた適切な権限を持つ MySQL ユーザー
• 書き込み操作の場合：INSERT、UPDATE、および／または DELETE 権限を持つ MySQL ユーザー

インストール

MCP サーバーをインストールして設定する方法はいくつかあります。

Claude Desktop

Claude Desktop アプリ用に MCP サーバーを手動で設定するには、次の内容を claude_desktop_config.json ファイル（通常はユーザーディレクトリ内にあります）に追加してください。

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "your_password",
        "MYSQL_DB": "your_database",
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false",
           "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
           "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
      }
    }
  }
}

Cursor

Cursor IDE の場合、プロジェクト内で次のコマンドを実行して、この MCP サーバーをインストールできます。

npx mcprunner MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASS=root MYSQL_DB=demostore ALLOW_INSERT_OPERATION=true ALLOW_UPDATE_OPERATION=true ALLOW_DELETE_OPERATION=false -- npx -y @benborla29/mcp-server-mysql

このコマンドの env の値を置き換えるのを忘れないでください。Cursor の最新バージョン（v0.47 以降）をお使いの場合は、以下の設定をコピーして貼り付けるだけです。

mcp.json

{
  "mcpServers": {
    "MySQL": {
      "command": "npx",
      "args": [
        "mcprunner",
        "MYSQL_HOST=127.0.0.1",
        "MYSQL_PORT=3306",
        "MYSQL_USER=root",
        "MYSQL_PASS=root",
        "MYSQL_DB=demostore",
        "ALLOW_INSERT_OPERATION=true",
        "ALLOW_UPDATE_OPERATION=true",
        "ALLOW_DELETE_OPERATION=false",
        "--",
        "npx",
        "-y",
        "@benborla29/mcp-server-mysql"
      ]
    }
  }
}

Smithery を使用する

この MCP サーバーをインストールして設定する最も簡単な方法は、Smithery を利用することです。

npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude

設定時に、MySQL の接続情報を入力するよう求められます。Smithery は次の処理を自動的に行います。

• 適切な環境変数を設定する
• MCP サーバーを使用するよう LLM アプリケーションを設定する
• MySQL データベースへの接続をテストする
• 必要に応じて役立つトラブルシューティング情報を提供する
• 書き込み操作の設定（INSERT、UPDATE、DELETE の権限）を行う

インストール時に、次の接続情報を求められます。

• MySQL ホスト（デフォルト：127.0.0.1）
• MySQL ポート（デフォルト：3306）
• MySQL ユーザー名
• MySQL パスワード
• MySQL データベース名
• SSL 設定（必要な場合）
• 書き込み操作の権限：
  • INSERT 操作を許可（デフォルト：false）
  • UPDATE 操作を許可（デフォルト：false）
  • DELETE 操作を許可（デフォルト：false）

セキュリティ上の理由から、書き込み操作はデフォルトで無効になっています。Claude にデータベースのデータを変更させる必要がある場合にのみ、有効にしてください。

MCP Get を使用する

MCP Get を使用してこのパッケージをインストールすることもできます。

npx @michaellatman/mcp-get@latest install @benborla29/mcp-server-mysql

MCP Get は MCP サーバーの一元管理されたレジストリを提供し、インストール手順を簡素化します。

NPM/PNPM を使用する

手動でインストールする場合：

# Using npm
npm install -g @benborla29/mcp-server-mysql

# Using pnpm
pnpm add -g @benborla29/mcp-server-mysql

手動でインストールした後、MCP サーバーを使用するよう LLM アプリケーションを設定する必要があります（下記の設定セクションを参照）。

ローカルリポジトリから実行する

この MCP サーバーをクローンしてソースコードから直接実行する場合は、次の手順に従ってください。

1. リポジトリをクローンする

   git clone https://github.com/benborla/mcp-server-mysql.git
   cd mcp-server-mysql
   

2. 依存関係をインストールする

   npm install
   # or
   pnpm install
   

3. プロジェクトをビルドする

   npm run build
   # or
   pnpm run build
   

4. Claude Desktop を設定する

   次の内容を Claude Desktop の設定ファイル（claude_desktop_config.json）に追加してください。

   {
     "mcpServers": {
       "mcp_server_mysql": {
         "command": "/path/to/node",
         "args": [
           "/full/path/to/mcp-server-mysql/dist/index.js"
         ],
         "env": {
           "MYSQL_HOST": "127.0.0.1",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "root",
           "MYSQL_PASS": "your_password",
           "MYSQL_DB": "your_database",
           "ALLOW_INSERT_OPERATION": "false",
           "ALLOW_UPDATE_OPERATION": "false",
           "ALLOW_DELETE_OPERATION": "false",
           "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
           "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
         }
       }
     }
   }
   

   次の値を置き換えてください。

   • /path/to/node を Node.js バイナリの完全なパスに置き換えます（which node で確認できます）
   • /full/path/to/mcp-server-mysql をリポジトリをクローンした場所の完全なパスに置き換えます
   • MySQL の認証情報を環境に合わせて設定します

5. サーバーをテストする

   # Run the server directly to test
   node dist/index.js
   

   MySQL に正常に接続できたら、Claude Desktop で使用する準備は完了です。

コンポーネント

ツール

• mysql_query
  • 接続されたデータベースに対して SQL クエリを実行します
  • 入力：sql（文字列）：実行する SQL クエリ
  • デフォルトでは、読み取り専用操作に制限されています
  • オプションで書き込み操作を有効にできます（設定による）：
    • INSERT：テーブルに新しいデータを追加します（ALLOW_INSERT_OPERATION=true が必要です）
    • UPDATE：既存のデータを変更します（ALLOW_UPDATE_OPERATION=true が必要です）
    • DELETE：データを削除します（ALLOW_DELETE_OPERATION=true が必要です）
  • すべての操作は、適切なコミット／ロールバック処理を行いながらトランザクション内で実行されます
  • 安全なパラメーター処理のため、プリペアドステートメントをサポートします
  • クエリのタイムアウトと結果のページネーションを設定できます
  • クエリ実行統計を標準で備えています

リソース

サーバーは、包括的なデータベース情報を提供します：

• テーブルスキーマ
  • 各テーブルの JSON スキーマ情報
  • 列名とデータ型
  • インデックス情報と制約
  • 外部キーの関係
  • テーブルの統計情報とメトリクス
  • データベースのメタデータから自動的に検出されます

セキュリティ機能

• プリペアドステートメントによる SQL インジェクションの防止
• クエリのホワイトリスト／ブラックリスト機能
• クエリ実行のレート制限
• クエリの複雑さの分析
• 接続の暗号化を設定可能
• 読み取り専用トランザクションの強制

パフォーマンスの最適化

• 最適化されたコネクションプーリング
• クエリ結果のキャッシュ
• 大規模な結果セットのストリーミング
• クエリ実行計画の分析
• クエリのタイムアウトを設定可能

モニタリングとデバッグ

• 包括的なクエリロギング
• パフォーマンスメトリクスの収集
• エラーの追跡とレポート
• ヘルスチェックエンドポイント
• クエリ実行統計

設定

Smithery による自動設定

Smithery を使用してインストールした場合、設定はすでに完了しています。次のコマンドで設定を表示または変更できます：

smithery configure @benborla29/mcp-server-mysql

再設定する際は、MySQL 接続の詳細に加えて、書き込み操作の設定も更新できます：

• 基本的な接続設定：

  • MySQL のホスト、ポート、ユーザー、パスワード、データベース
  • SSL/TLS の設定（データベースでセキュアな接続が必要な場合）

• 書き込み操作の権限：

  • INSERT 操作を許可：新しいデータの追加を許可する場合は true に設定します
  • UPDATE 操作を許可：既存データの更新を許可する場合は true に設定します
  • DELETE 操作を許可：データの削除を許可する場合は true に設定します

セキュリティ上の理由から、すべての書き込み操作はデフォルトで無効になっています。Claude にデータベースのデータを変更させる必要がある場合に限り、これらの設定を有効にしてください。

高度な設定オプション

MCP サーバーの動作をより細かく制御するには、次の高度な設定オプションを使用できます：

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        // Basic connection settings
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",
        
        // Performance settings
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        
        // Security settings
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        
        // Monitoring settings
        "MYSQL_ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true",
        
        // Write operation flags
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

環境変数

基本的な接続設定

• MYSQL_HOST：MySQL サーバーのホスト（デフォルト："127.0.0.1"）
• MYSQL_PORT：MySQL サーバーのポート（デフォルト："3306"）
• MYSQL_USER：MySQL のユーザー名（デフォルト："root"）
• MYSQL_PASS：MySQL のパスワード
• MYSQL_DB：対象のデータベース名（複数データベースモードを使用する場合は空欄にします）

パフォーマンス設定

• MYSQL_POOL_SIZE：コネクションプールのサイズ（デフォルト："10"）
• MYSQL_QUERY_TIMEOUT：クエリのタイムアウト（ミリ秒）（デフォルト："30000"）
• MYSQL_CACHE_TTL：キャッシュの有効期間（ミリ秒）（デフォルト："60000"）

セキュリティ設定

• MYSQL_RATE_LIMIT：1 分あたりの最大クエリ数（デフォルト："100"）
• MYSQL_MAX_QUERY_COMPLEXITY：クエリの複雑さの最大スコア（デフォルト："1000"）
• MYSQL_SSL：SSL/TLS 暗号化を有効にします（デフォルト："false"）
• ALLOW_INSERT_OPERATION：INSERT 操作を有効にします（デフォルト："false"）
• ALLOW_UPDATE_OPERATION：UPDATE 操作を有効にします（デフォルト："false"）
• ALLOW_DELETE_OPERATION：DELETE 操作を有効にします（デフォルト："false"）
• ALLOW_DDL_OPERATION：DDL 操作を有効にします（デフォルト："false"）
• SCHEMA_INSERT_PERMISSIONS：スキーマ固有の INSERT 権限
• SCHEMA_UPDATE_PERMISSIONS：スキーマ固有の UPDATE 権限
• SCHEMA_DELETE_PERMISSIONS：スキーマ固有の DELETE 権限
• SCHEMA_DDL_PERMISSIONS：スキーマ固有の DDL 権限
• MULTI_DB_WRITE_MODE：マルチ DB モードで書き込み操作を有効にします（デフォルト："false"）

モニタリング設定

• MYSQL_ENABLE_LOGGING：クエリのログ記録を有効にします（デフォルト："false"）
• MYSQL_LOG_LEVEL：ログレベル（デフォルト："info"）
• MYSQL_METRICS_ENABLED：パフォーマンス指標を有効にします（デフォルト："false"）

マルチ DB モード

MCP-Server-MySQL は、特定のデータベースが設定されていない場合に、複数のデータベースへの接続をサポートします。これにより、LLM は MySQL ユーザーがアクセスできる任意のデータベースにクエリを実行できます。詳細については、README-MULTI-DB.md を参照してください。

マルチ DB モードを有効にする

マルチ DB モードを有効にするには、MYSQL_DB 環境変数を空のままにします。マルチ DB モードでは、クエリでスキーマを指定する必要があります。

-- Use fully qualified table names
SELECT * FROM database_name.table_name;

-- Or use USE statements to switch between databases
USE database_name;
SELECT * FROM table_name;

スキーマ固有の権限

データベース操作をきめ細かく制御するため、MCP-Server-MySQL はスキーマ固有の権限をサポートするようになりました。これにより、データベースごとに異なるアクセスレベル（読み取り専用、読み書き可能など）を設定できます。

設定例

SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false

詳細およびセキュリティに関する推奨事項については、README-MULTI-DB.md を参照してください。

テスト

データベースのセットアップ

テストを実行する前に、テスト用データベースをセットアップし、テストデータを投入する必要があります。

1. テスト用データベースとユーザーを作成

   -- Connect as root and create test database
   CREATE DATABASE IF NOT EXISTS mcp_test;
   
   -- Create test user with appropriate permissions
   CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';
   GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';
   FLUSH PRIVILEGES;
   

2. データベースのセットアップスクリプトを実行

   # Run the database setup script
   pnpm run setup:test:db
   

   これにより、必要なテーブルが作成され、シードデータが投入されます。スクリプトは scripts/setup-test-db.ts にあります。

3. テスト環境を設定 プロジェクトのルートに .env.test ファイルを作成します（まだ存在しない場合）。

   MYSQL_HOST=127.0.0.1
   MYSQL_PORT=3306
   MYSQL_USER=mcp_test
   MYSQL_PASS=mcp_test_password
   MYSQL_DB=mcp_test
   

4. package.json のスクリプトを更新 これらのスクリプトを package.json に追加します。

   {
     "scripts": {
       "setup:test:db": "ts-node scripts/setup-test-db.ts",
       "pretest": "pnpm run setup:test:db",
       "test": "vitest run",
       "test:watch": "vitest",
       "test:coverage": "vitest run --coverage"
     }
   }
   

テストの実行

このプロジェクトには、機能と信頼性を確保するための包括的なテストスイートが含まれています。

# First-time setup
pnpm run setup:test:db

# Run all tests
pnpm test

トラブルシューティング

よくある問題

1. 接続の問題

   • MySQL サーバーが実行中で、アクセス可能であることを確認します
   • 認証情報と権限を確認します
   • SSL/TLS が有効な場合は、設定が正しいことを確認します
   • MySQL クライアントで接続し、アクセスできることを確認します

2. パフォーマンスの問題

   • 接続プールのサイズを調整します
   • クエリのタイムアウト値を設定します
   • 必要に応じてクエリキャッシュを有効にします
   • クエリの複雑さに関する設定を確認します
   • サーバーのリソース使用状況を監視します

3. セキュリティ上の制限

   • レート制限の設定を確認します
   • クエリの許可リスト／拒否リストの設定を確認します
   • SSL/TLS の設定を確認します
   • ユーザーに適切な MySQL 権限があることを確認します

4. パスの解決 「Could not connect to MCP server mcp-server-mysql」というエラーが発生した場合は、必要なバイナリすべてのパスを明示的に設定してください：

{
  "env": {
    "PATH": "/path/to/node/bin:/usr/bin:/bin"
  }
}

node の bin パスはどこで確認できますか 次のコマンドを実行して確認します：

PATH の場合

echo "$(which node)/../"    

NODE_PATH の場合

echo "$(which node)/../../lib/node_modules"    

5. Claude Desktop 固有の問題

   • Claude Desktop のログに「Server disconnected」と表示される場合は、~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log のログを確認します
   • Node バイナリとサーバースクリプトの両方に絶対パスを使用していることを確認します
   • .env ファイルが正しく読み込まれているか確認します。設定で環境変数を明示的に指定してください
   • サーバーをコマンドラインから直接実行し、接続に問題がないか確認します
   • 書き込み操作（INSERT、UPDATE、DELETE）が必要な場合は、設定で該当するフラグを「true」にします：

     "env": {
       "ALLOW_INSERT_OPERATION": "true",  // INSERT 操作を有効にする
       "ALLOW_UPDATE_OPERATION": "true",  // UPDATE 操作を有効にする
       "ALLOW_DELETE_OPERATION": "true"   // DELETE 操作を有効にする
     }
     

   • 有効にする操作に必要な権限が MySQL ユーザーに付与されていることを確認します
   • 直接実行するための設定には、次を使用します：

     {
       "mcpServers": {
         "mcp_server_mysql": {
           "command": "/full/path/to/node",
           "args": [
             "/full/path/to/mcp-server-mysql/dist/index.js"
           ],
           "env": {
             "MYSQL_HOST": "127.0.0.1",
             "MYSQL_PORT": "3306",
             "MYSQL_USER": "root",
             "MYSQL_PASS": "your_password",
             "MYSQL_DB": "your_database"
           }
         }
       }
     }
     

6. 認証の問題

   • MySQL 8.0 以降では、サーバーが caching_sha2_password 認証プラグインをサポートしていることを確認します
   • MySQL ユーザーに正しい認証方式が設定されているか確認します
   • 必要に応じて、従来の認証方式を使用するユーザーを作成します：

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
     

     @lizhuangs

7. Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from エラーが発生する場合 次の回避策を試してください：

npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql

@lizhuangs に感謝します

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください： https://github.com/benborla/mcp-server-mysql

開発環境のセットアップ

1. リポジトリをクローンします
2. 依存関係をインストールします：pnpm install
3. プロジェクトをビルドします：pnpm run build
4. テストを実行します：pnpm test

プロジェクトのロードマップ

この MCP サーバーの機能強化に取り組んでいます。予定されている機能の詳細は、CHANGELOG.md を確認してください。次の内容が含まれます：

• プリペアドステートメントによるクエリ機能の強化
• 高度なセキュリティ機能
• パフォーマンスの最適化
• 包括的な監視機能
• スキーマ情報の拡充

これらの分野への貢献をご希望の場合は、GitHub で Issue を確認するか、新しい Issue を作成してアイデアを話し合ってください。

変更の提出

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/your-feature-name
3. 変更をコミットします：git commit -am 'Add some feature'
4. ブランチにプッシュします：git push origin feature/your-feature-name
5. プルリクエストを送信します

ライセンス

この MCP サーバーは MIT License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。