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

MySQLデータベースへのアクセスを提供するモデルコンテキストプロトコル（CMP）サーバー。このサーバーにより、LLMはデータベーススキーマを検査し、SQLクエリを実行できます。

目次

• 要件
• インストール
  • クロードデスクトップ
  • カーソル
  • 鍛冶屋
  • MCP ゲット
  • ローカルリポジトリへのクローン
• コンポーネント
• 構成
• 環境変数
• マルチDBモード
• スキーマ固有の権限
• テスト
• トラブルシューティング
• 貢献
• ライセンス

要件

• Node.js v18以上
• MySQL 5.7 以上 (MySQL 8.0 以上を推奨)
• 必要な操作に適切な権限を持つ MySQL ユーザー
• 書き込み操作の場合: INSERT、UPDATE、および/またはDELETE権限を持つMySQLユーザー

インストール

MCP サーバーをインストールして構成するには、いくつかの方法があります。

クロードデスクトップ

Claude デスクトップ アプリ用に MCP サーバーを手動で構成するには、 claude_desktop_config.jsonファイル (通常はユーザー ディレクトリにあります) に次のコードを追加します。

カーソル

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

このコマンドのenv変数の値を忘れずに置き換えてください。Cursorの最新バージョン（v0.47以降）をお持ちの場合は、以下の設定をコピー＆ペーストしてください。

mcp.json

鍛冶屋を使う

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

設定中に、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を使用してインストールすることもできます。

MCP Get は、MCP サーバーの集中レジストリを提供し、インストール プロセスを簡素化します。

NPM/PNPMの使用

手動インストールの場合:

手動でインストールした後、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デスクトップの設定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_クエリ
  • 接続されたデータベースに対してSQLクエリを実行する
  • 入力: sql (文字列): 実行するSQLクエリ
  • デフォルトでは読み取り専用操作に制限されています
  • オプションの書き込み操作（構成により有効になっている場合）:
    • INSERT: テーブルに新しいデータを追加します ( ALLOW_INSERT_OPERATION=trueが必要です)
    • UPDATE: 既存のデータを変更する ( ALLOW_UPDATE_OPERATION=trueが必要)
    • DELETE: データを削除します（ ALLOW_DELETE_OPERATION=trueが必要です）
  • すべての操作は、適切なコミット/ロールバック処理を伴うトランザクション内で実行されます。
  • 安全なパラメータ処理のための準備済みステートメントをサポート
  • 設定可能なクエリタイムアウトと結果のページ区切り
  • 組み込みクエリ実行統計

リソース

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

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

セキュリティ機能

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

パフォーマンスの最適化

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

監視とデバッグ

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

構成

Smitheryによる自動構成

Smitheryを使用してインストールした場合、設定は既に完了しています。以下のコマンドで設定を確認または変更できます。

再構成時に、MySQL 接続の詳細と書き込み操作の設定を更新できます。

• 基本的な接続設定：
  • MySQL ホスト、ポート、ユーザー、パスワード、データベース
  • SSL/TLS 構成 (データベースに安全な接続が必要な場合)
• 書き込み操作権限:
  • INSERT操作を許可: 新しいデータの追加を許可する場合はtrueに設定します
  • 更新操作を許可: 既存のデータの更新を許可する場合は true に設定します
  • DELETE操作を許可: データの削除を許可する場合はtrueに設定します

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

高度な設定オプション

MCP サーバーの動作をさらに制御するには、次の高度な構成オプションを使用できます。

環境変数

基本接続

• MYSQL_HOST : MySQLサーバーのホスト（デフォルト: "127.0.0.1")
• MYSQL_PORT : MySQLサーバーのポート（デフォルト: "3306"）
• MYSQL_USER : MySQLユーザー名（デフォルト: "root")
• MYSQL_PASS : MySQLパスワード
• MYSQL_DB : ターゲットデータベース名（マルチ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モードでは、クエリにスキーマ修飾が必要です。

スキーマ固有の権限

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

設定例

完全な詳細とセキュリティ推奨事項については、 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" } }

テストの実行

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

トラブルシューティング

よくある問題

1. 接続の問題
   • MySQLサーバーが実行中でアクセス可能であることを確認する
   • 資格情報と権限を確認する
   • SSL/TLS が有効になっている場合は、設定が正しいことを確認します。
   • MySQLクライアントで接続してアクセスを確認してください
2. パフォーマンスの問題
   • 接続プールのサイズを調整する
   • クエリのタイムアウト値を構成する
   • 必要に応じてクエリキャッシュを有効にする
   • クエリの複雑さの設定を確認する
   • サーバーリソースの使用状況を監視する
3. セキュリティ制限
   • レート制限設定を確認する
   • クエリのホワイトリスト/ブラックリスト設定を確認する
   • SSL/TLS設定を確認する
   • ユーザーに適切なMySQL権限があることを確認する
4. パスの解決「MCP サーバー mcp-server-mysql に接続できませんでした」というエラーが発生した場合は、必要なすべてのバイナリのパスを明示的に設定します。

nodeの bin パスはどこで確認できますか? 取得するには次のコマンドを実行します。

PATHの場合

NODE_PATHの場合

5. クロードデスクトップ特有の問題
   • Claude Desktop に「サーバーが切断されました」というログが表示される場合は、 ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.logのログを確認してください。
   • Nodeバイナリとサーバースクリプトの両方への絶対パスを使用していることを確認してください
   • .envファイルが正しく読み込まれているかどうかを確認します。設定で明示的な環境変数を使用します。
   • コマンドラインから直接サーバーを実行して、接続に問題がないか確認してください。
   • 書き込み操作 (INSERT、UPDATE、DELETE) が必要な場合は、構成で適切なフラグを「true」に設定します。
     "env": { "ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations "ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations "ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations }
   • 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 。次の回避策を試してください。

@lizhuangsに感謝します

貢献

貢献を歓迎します！お気軽にhttps://github.com/benborla/mcp-server-mysqlにプルリクエストを送信してください。

開発セットアップ

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

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

MCPサーバーの機能強化に積極的に取り組んでいます。計画されている機能の詳細については、 CHANGELOG.mdをご覧ください。

• 準備されたステートメントによるクエリ機能の強化
• 高度なセキュリティ機能
• パフォーマンスの最適化
• 包括的な監視
• 拡張スキーマ情報

これらのいずれかの分野に貢献したい場合は、GitHub の問題を確認するか、新しい問題を開いてアイデアについて話し合ってください。

変更の送信

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ファイルをご覧ください。