read-only-local-mysql-mcp-server

MySQL MCP Server

自然言語でのクエリを通じて、Claude Desktop から MySQL データベースを操作できる Model Context Protocol（MCP）サーバーです。

機能

• Claude Desktop を通じて読み取り専用の SQL クエリを実行
• 動的な接続設定 — 接続文字列を使用して、実行時に任意の MySQL データベースへ接続
• クエリ検証（SELECT、WITH、SHOW、DESCRIBE、EXPLAIN のみ、単一ステートメント、コメントなし）に加え、サーバー側の読み取り専用トランザクションによる組み込みのセキュリティ
• Claude Desktop と簡単に連携
• JSON 形式のクエリ結果
• データベースの認証情報を環境変数で設定

クイックスタート

Claude Code ユーザー向け（推奨 — 最も簡単な方法）

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

次に、データベースの環境変数を設定します。

export DB_HOST=localhost
export DB_PORT=3306
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

これで完了です！ Claude Code を再起動して、「データベースにはどのテーブルがありますか？」と尋ねてください。

Claude Desktop ユーザー向け（手動設定）

1. 設定ファイルを開きます。

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. 次の設定を追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. 保存して Claude Desktop を再起動し、テストします！

前提条件

• Node.js（v16 以降）— mise を使用している場合は、コマンドのパスを適宜更新してください
• MySQL データベースサーバー
• Claude Desktop アプリケーション

インストール

オプション 1：MCP Registry からインストール（推奨）

このサーバーは、Model Context Protocol Registry に capital.hove/read-only-local-mysql-mcp-server として公開されています。

方法 A：Claude Code CLI（最も簡単！）

claude mcp add mysql -s user -- npx -y @hovecapital/read-only-mysql-mcp-server@latest

次に、環境変数を使ってデータベースの認証情報を設定します。Claude Code を再起動すれば完了です！

メリット：

• 1 つのコマンドでインストール
• JSON の手動編集が不要
• 自動設定

方法 B：JSON を手動で設定

Claude Desktop の場合：

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code の場合：

~/.config/claude-code/settings.json（macOS/Linux）または %APPDATA%\claude-code\settings.json（Windows）を編集します。

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-mysql-mcp-server@latest"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

オプション 2：npm からインストール

npm install -g @hovecapital/read-only-mysql-mcp-server

オプション 3：Claude Code でインストール

Claude Code を使用している場合は、この MCP サーバーを簡単にインストールできます。

# Clone the repository
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git
cd read-only-local-mysql-mcp-server

# Install dependencies and build
npm install
npm run build

その後、MCP 設定に追加して Claude Code を設定します。

オプション 4：手動インストール

1. クローンまたはダウンロード

リポジトリをシステム上のディレクトリに保存します。

mkdir ~/mcp-servers/mysql
cd ~/mcp-servers/mysql
git clone https://github.com/hovecapital/read-only-local-mysql-mcp-server.git .

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

npm install
npm run build

設定

注： オプション 1（MCP Registry から npx でインストール）を選択した場合は、すでにすべての設定が完了しています。このセクションは、オプション 2、3、4（npm または手動インストール）を選択したユーザー向けです。

Claude Code の設定

手動インストールで Claude Code を使用する場合は、MCP 設定に MySQL サーバーを追加します。

1. Claude Code の設定を開きます（通常、macOS/Linux では ~/.config/claude-code/settings.json、Windows では %APPDATA%\claude-code\settings.json にあります）。

2. MySQL MCP サーバーの設定を追加します。

{
  "mcp": {
    "servers": {
      "mysql": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "3306",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

1. 変更を反映するため、Claude Code を再起動します。

Claude Desktop の設定

手動インストールで Claude Desktop を使用する場合は、Claude Desktop の設定ファイルを開きます。

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

MySQL サーバーの設定を追加します。

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-mysql-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

Node.js で mise を使用する

Node.js のバージョン管理に mise を使用している場合は、設定で Node.js 実行ファイルのフルパスを指定してください。

環境変数

変数	説明	デフォルト
DB_HOST	MySQL サーバーのホスト名	mysql
DB_PORT	MySQL サーバーのポート	3306
DB_DATABASE	データベース名	database
DB_USERNAME	MySQL のユーザー名	root
DB_PASSWORD	MySQL のパスワード	(empty)
DB_ALLOWED_HOSTS	接続文字列で指定できる追加ホスト（カンマ区切り）。DB_HOST とループバックは常に許可されます。	(empty)

使い方

1. 設定を更新した後、Claude Desktop を再起動します
2. データベースについて Claude とチャットを開始します

クエリの例

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

Claude は自然言語でのリクエストを適切な SQL クエリに自動的に変換し、データベースに対して実行します。

ツール

connect

接続文字列を使用して MySQL データベースに接続します。接続は、変更または切断されるまで後続のクエリでも維持されます。

パラメーター：

パラメーター	必須	説明
connectionString	はい	MySQL 接続文字列（例：mysql://user:password@host:port/database）

disconnect

現在のランタイムデータベースから切断し、デフォルトの環境変数で設定された接続に戻します。パラメーターはありません。

query

現在接続中のデータベースに対して、読み取り専用の SQL クエリを実行します。

パラメーター：

パラメーター	必須	説明
sql	はい	実行する SQL クエリ（読み取り専用）
connectionString	いいえ	このクエリに限り、現在の接続を上書きする MySQL 接続文字列

動的な接続

サーバーは再起動せずに、実行時にデータベースを切り替えることができます。接続の優先順位は次のとおりです。

1. クエリごとの connectionString — 単一のクエリに限り、すべてを上書きします
2. ランタイム接続（connect ツールによる接続） — disconnect が呼び出されるまで維持されます
3. 環境変数 — デフォルトのフォールバック

接続文字列の形式：

mysql://username:password@hostname:port/database_name

ホスト名は DB_HOST、ループバックアドレス、または DB_ALLOWED_HOSTS に登録されたホストである必要があります。それ以外のホストは接続を試みる前に拒否されるため、ツールを使ってネットワークを探索することはできません。接続に失敗した場合は一般的なメッセージが返され、実際のエラーは stderr に書き込まれます。

ワークフローの例：

1. connect → mysql://analyst:pass@prod-db:3306/analytics
2. query   → SELECT COUNT(*) FROM events
3. query   → SELECT * FROM users LIMIT 5 (uses the same analytics connection)
4. query   → SELECT * FROM orders LIMIT 5, connectionString: mysql://analyst:pass@prod-db:3306/sales
              (one-off override — does not change the stored connection)
5. disconnect → reverts to env var defaults

セキュリティ機能

読み取り専用操作

クエリは次の 2 つの層でチェックされます。

1. クエリの検証 — ステートメントは SELECT、WITH、SHOW、DESCRIBE、EXPLAIN のいずれかで始まり、単一のステートメントのみを含み、コメントを含まず、状態を変更するキーワードをどこにも含まない必要があります（例：UPDATE、DELETE、INTO OUTFILE、INTO DUMPFILE、LOAD_FILE、FOR UPDATE、EXPLAIN ANALYZE）。このチェックでは、文字列リテラルとバッククォートで囲まれた識別子は無視されます。
2. サーバー側の読み取り専用トランザクション — すべてのクエリは SET SESSION TRANSACTION READ ONLY の実行後に実行されるため、保存関数内での書き込みも含め、MySQL 自体が書き込みを拒否します。

MySQL ユーザーには SELECT 権限のみを付与してください（以下を参照）。検証によって既知の回避方法はブロックされますが、最終的な保証となるのはデータベースの権限です。

推奨するデータベース設定

セキュリティを強化するには、MCP サーバー専用の読み取り専用ユーザーを作成します。

-- Create a read-only user
CREATE USER 'claude_readonly'@'localhost' IDENTIFIED BY 'secure_password';

-- Grant only SELECT permissions on your specific database
GRANT SELECT ON your_database_name.* TO 'claude_readonly'@'localhost';

-- Apply the changes
FLUSH PRIVILEGES;

トラブルシューティング

接続の問題

1. MySQL が稼働していることを確認する：MySQL サーバーがアクティブかどうか確認します
2. 認証情報を確認する：ユーザー名とパスワードが正しいことを確認します
3. ネットワーク接続を確認する：Claude Desktop から MySQL サーバーに接続できることを確認します

設定の問題

1. 再起動が必要です：設定を変更した後は、必ず Claude Desktop を再起動します
2. パスの正確性：dist/index.js への絶対パスが正しいことを確認します
3. JSON 構文：claude_desktop_config.json の形式を検証します

デバッグモード

サーバーログを確認するには、サーバーを手動で実行します。

node dist/index.js

ファイル構成

~/mcp-servers/mysql/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

依存関係

• @modelcontextprotocol/sdk：MCP プロトコルの実装
• mysql2：Promise に対応した、Node.js 用の最新の MySQL クライアント

コントリビューション

問題の報告や機能改善のリクエストをぜひお寄せください！

ライセンス

このプロジェクトはオープンソースで、MIT ライセンスに基づいて公開されています。

サポート

問題が発生した場合は、次の項目をご確認ください。

1. 上記のトラブルシューティングのセクションを確認してください
2. MySQL 接続を個別に検証してください
3. Claude Desktop が最新バージョンに更新されていることを確認してください
4. Claude Desktop の MCP ドキュメントを確認してください

---

注：このサーバーは開発および分析を目的として設計されています。本番環境で使用する場合は、追加のセキュリティ対策と監視を検討してください。