MCP Server for MySQL based on NodeJS

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

MySQL データベースへの読み取り専用アクセスを提供する Model Context Protocol サーバーです。このサーバーを使用すると、LLM がデータベーススキーマを調査し、読み取り専用クエリを実行できます。

インストール

Smithery を使用する

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

# Install the MCP server
npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude

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

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

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 アプリケーションを設定する必要があります（下記の「設定」セクションを参照）。

コンポーネント

ツール

• mysql_query
  • 接続先のデータベースに対して読み取り専用 SQL クエリを実行します
  • 入力：sql（文字列）：実行する SQL クエリ
  • すべてのクエリは READ ONLY トランザクション内で実行されます
  • 安全なパラメーター処理のため、プリペアドステートメントをサポートします
  • クエリのタイムアウトと結果のページネーションを設定できます
  • クエリ実行統計機能を内蔵しています

リソース

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

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

セキュリティ機能

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

パフォーマンスの最適化

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

監視とデバッグ

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

設定

Smithery による自動設定

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

smithery configure @benborla29/mcp-server-mysql

Claude Desktop App の手動設定

Claude Desktop App 用に 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": "",
        "MYSQL_DB": "db_name"
      }
    }
  }
}

db_name はデータベース名に置き換えてください。または、空欄のままにするとすべてのデータベースにアクセスできます。

高度な設定オプション

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

環境変数

基本的な接続

• 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"）

モニタリングの設定

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

テスト

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

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

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

トラブルシューティング

Smithery を使ったトラブルシューティング

Smithery を使ってインストールした場合は、組み込みの診断機能を使用できます。

# Check the status of your MCP server
smithery status @benborla29/mcp-server-mysql

# Run diagnostics
smithery diagnose @benborla29/mcp-server-mysql

# View logs
smithery logs @benborla29/mcp-server-mysql

MCP Get を使ったトラブルシューティング

MCP Get を使ってインストールした場合：

# Check the status
mcp-get status @benborla29/mcp-server-mysql

# View logs
mcp-get logs @benborla29/mcp-server-mysql

よくある問題

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

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

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

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。 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 ファイルを参照してください。