Claude Media
Claude CodeにRavenDB MCPをつないでクラスターを読み取り専用で診断する
Claude CodeMCPClaude連携チュートリアル

Claude CodeにRavenDB MCPをつないでクラスターを読み取り専用で診断する

RavenDB MCPをClaude Codeに登録し、クラスターの状態を読み取り専用で診断させる手順です。証明書の権限、秘密のマスクが効かない範囲、permissionsの絞り込みまで扱います。

読了目安 約16分

RavenDB MCPは、RavenDBクラスターの状態を調べるための読み取り専用MCPサーバーです。Claude Codeに登録すると、「データベースの一覧を出して」「インデックスの状態を見て」といった診断をチャットで頼めます。書き込みや削除のツールは用意されていません。

この記事では、登録から接続確認、証明書の権限設計、そして読み取り専用でも気をつけたい点までを順に扱います。クラスターを調べさせる側の設定(Claude CodeのpermissionsとCLAUDE.md)も具体例で示します。

RavenDB MCPとは何で、どこで動くか

RavenDB MCPは、RavenDB社が提供するローカル実行のMCPサーバーです。手元のマシンでプロセスとして動き、指定したクラスターのURLにだけ接続します。クラスター、データベース、インデックス、タスク、ストレージ、パフォーマンスの状態に加えて、ログ、サポートパッケージ、ドキュメントの中身まで、21の読み取り専用ツールで参照できます。

READMEによると、テレメトリーや分析のための通信はなく、RavenDBにもAnthropicにもデータは送られません。外へ出る通信は、npxやdnxで入れるときのnpm・NuGetからのダウンロードだけです。

Claudeのコネクタ一覧では「Anthropic verified」の表示つきで掲載されています。Claude Codeではclaude mcp addで自分で登録する方法が基本になります。

21ツールは74から集約された

ツールは「対象ごとに1つ」の形にまとめられています。以前は74あったものを21に減らし、引数で見たい部分を選ぶ作りです。ツール定義がコンテキストを圧迫しにくくなる設計です。

名前は次のとおりです(いずれもsnake_case)。

区分ツール
引数で見る範囲を選ぶもの(15)ツールget_cluster_overview / get_server_config / get_server_resources / get_network_details / get_database_stats / get_database_config / get_index / get_tasks / get_live_workload / inspect_storage / get_document_data / sample_live_feed / wait_for_completion / collect_debug_package / get_ai_agents
単独で動くもの(6)ツールlist_databases / get_database_record / get_notifications / run_query / list_compare_exchange / export_server_logs

出力が大きくなりやすい仕組みへの対策も入っています。既定では概要だけを返し、必要に応じて詳細へ掘り下げます。一覧系はpageSizeでページ分割され、run_queryはstartとpageSize(最大128行)を取ります。ログの書き出しとデバッグパッケージは、中身ではなくファイルのパスとバイト数が返ります。

Claude Codeに登録して接続を確かめる

必要なのは、クラスターのURLを指すRAVENDB_URLSだけです。起動コマンドにはnpx(Node.js 18以上)、dnx(.NET 10 SDK)、ビルド済みバイナリのどれかを選べます。バイナリなら実行環境の追加導入は要りません。

claude mcp add ravendb --scope user \
  --env RAVENDB_URLS=http://localhost:8080 \
  -- npx -y @ravendb/mcp

--より前がClaude Code側のオプション、後ろがサーバーを起動するコマンドです。--以降はそのままサーバーに渡されます。

登録先は--scopeで変わります。省略するとローカルスコープになり、登録したプロジェクトでだけ使える私的な設定として~/.claude.jsonに保存されます。READMEの例は--scope userで、どのプロジェクトからも同じ設定で呼べます。接続先が開発用クラスターならユーザースコープ、特定の案件専用なら省略したローカルスコープ、という分け方が収まりがよい選び方です。

プラグインとして入れる方法もあります。こちらはクラスターのURLを対話で聞かれます。

/plugin marketplace add ravendb/ravendb-mcp
/plugin install ravendb-mcp@ravendb

登録後は接続状態を確かめます。

claude mcp list          # サーバーごとの接続状態
claude mcp get ravendb   # 解決済みのコマンド・引数・環境変数

Claude Codeのセッション内で/mcpを開いてから、「list my RavenDB databases」や「show cluster overview」と頼めば動作を確かめられます。ツールが出てこないときは、新しいセッションを始めてください。サーバーはセッション開始時に読み込まれます。

設定を変えるときは、claude mcp remove ravendbで外してから登録し直します。npxとdnxの経路は起動のたびに公開済みの最新版を取りに行くため、サーバー自体の更新作業はありません。

認証つきクラスターへつなぐ:証明書の権限がそのまま上限になる

本番のRavenDBは多くの場合HTTPSで、クライアント証明書(.pfx)で認証します。登録コマンドに証明書の変数を足します。

claude mcp add ravendb --scope user \
  --env RAVENDB_URLS=https://node-a.example.development.run:443 \
  --env RAVENDB_CERTIFICATE_PATH=/path/to/client.certificate.pfx \
  --env RAVENDB_CERTIFICATE_PASSWORD=pfxPasswordIfAny \
  -- npx -y @ravendb/mcp

.pfxにパスワードがなければ、パスワードの変数は省きます。HTTPのクラスターでは証明書の設定をどちらも空にします。この場合、サーバーは暗号化されない通信になることを起動時に警告します。

ここで読み取り専用の線引きを決めるのが、証明書の権限です。サーバー側が書き込み系のツールを持たないことに加えて、アクセスはクライアント証明書のRavenDB上の権限に縛られます。権限の目安は次のとおりです。

  • データベース・インデックス・クエリ・ドキュメント系のツール: データベース単位のRead権限の証明書で足ります
  • サーバー全体・クラスター全体を見るツール: Operator相当の権限が必要です

最初はRead権限の証明書だけを渡し、サーバー全体の診断が必要になった時点でOperatorの証明書に切り替える運用だと、AIに見せる範囲を段階的に広げられます。証明書はRavenDB StudioのManage Server > Certificatesで発行します。

複数ノードのクラスターは、ノードのURLをカンマ区切りでRAVENDB_URLSに並べます。クライアントは並べたURLの間でフェイルオーバーしますが、診断用の生のルートは先頭のURLに向かいます。1つのサーバーが対象にできるクラスターは1つだけなので、別のクラスターを見たいときは別名でもう1つ登録します。

パスワードは.pfxを開くプロセス内でだけ使われ、ログにもディスクにも書かれないと説明されています。ただし、claude mcp addに渡した値は~/.claude.jsonに残ります。シェルの履歴やリポジトリにパスワードが入り込まないよう、.mcp.jsonで共有するときは環境変数の展開を使うほうが無難です。

診断の頼み方:症状から入り、ツールは任せる

ツール名を覚える必要はありません。症状や知りたいことを日本語で伝えれば、Claudeが適切なツールを選びます。頼み方の例を挙げます。

  • 「クラスターの状態を概要で見て、異常があれば該当ノードを教えて」
  • 「Ordersデータベースのインデックスの状態を確認して」
  • 「実行中のタスクを一覧にして、止まっているものがないか見て」
  • 「このクエリが遅い。実行して、パーサーのエラーが出たらRQLの書き方を確認して」

RQL(RavenDBのクエリ言語)の資料は、バージョンに合った内容がrql://リソースとして提供されます。クエリが失敗したときは、パーサーのエラーと参照先が返ります。Claudeが書いたRQLを誤っても、そのエラーを手がかりに書き直せます。

書き込み系のクエリ(データを変更するもの)は拒否されます。「読み取り専用のはずなのに、パッチ文を投げてしまった」という事故は、サーバー側で止まります。

読み取り専用でも出ていくもの:マスクされる範囲とされない範囲

「読み取り専用」が守るのはデータの変更です。データがClaudeに渡ること自体は、設計どおりに起きます。ここは3つに分けて押さえてください。

マスクされるもの。接続文字列の秘密(パスワード、クラウドのアクセスキー、SASトークン、AIプロバイダーのAPIキー、証明書)は、返されるJSONの中で***redacted***に置き換わります。データベースレコード、バックアップ・ETL・レプリケーションのタスク設定、サーバー設定、AIエージェント設定が対象です。

マスクされないもの。ログの書き出し(export_server_logs)、ライブフィード(AdminLogsとTrafficWatchのサンプル)、デバッグパッケージ(collect_debug_package)は、加工されずにそのまま返ります。構造化されていないテキストに混じった秘密は、機械的に隠せないためです。これらは機密として扱う必要があります。

そもそも隠さないもの。 get_document_dataとrun_queryは、クラスターの実データをAIのコンテキストに入れます。顧客情報が入ったコレクションに対してクエリを実行させれば、その行がセッションの記録に残ります。

書き出されたファイルは、既定ではシステムの一時フォルダー内のravendb-mcp-artifactsに作られ、LinuxとmacOSではユーザーだけが読める権限(0700)になります。RAVENDB_ARTIFACTS_PATHで場所を指定すると権限の変更は行われず、保管期間と掃除は利用者の責任になります。

Claude Code側でも絞る:permissionsとCLAUDE.md

サーバー側の制限に加えて、Claude Codeのpermissionsで呼べるツールを絞れます。登録名をravendbにしているため、ツール名はmcp__ravendb__<ツール名>の形になります。公式のpermissionsの書き方では、許可ルールのワイルドカードはmcp__<サーバー名>__のあとにだけ使えます。

次の例は、マスクの対象外であるログ・ライブフィード・デバッグパッケージの3ツールを拒否し、名前がget_またはlist_で始まるツールを許可する設定です(.claude/settings.json)。

{
  "permissions": {
    "allow": ["mcp__ravendb__get_*", "mcp__ravendb__list_*"],
    "deny": [
      "mcp__ravendb__export_server_logs",
      "mcp__ravendb__collect_debug_package",
      "mcp__ravendb__sample_live_feed"
    ]
  }
}

get_document_dataもget_で始まるため、この許可に含まれます。実データを返すツールまで自動で通したくなければ、get_document_dataとrun_queryをaskに入れて、呼び出しのたびに確認が出るようにしておきます。

CLAUDE.mdには、調べ方の約束を書いておくと、毎回同じ手順で調べるようになります。次は書き方の一例です。

## RavenDBの診断ルール
- 最初に get_cluster_overview で全体を見てから、必要なデータベースに絞る
- run_query は pageSize を 20 以下にして、個人情報を含むフィールドは選ばない
- 調査結果には、使ったツール名と対象データベース名を書く
- ログやデバッグパッケージは取得しない。必要なときは人に依頼する

この約束はClaudeが守る前提の指示で、強制力があるのはpermissionsのほうです。ログの取得を確実に防ぎたいなら、CLAUDE.mdの1行に頼らずdenyに入れてください。

診断を頼むデータベースの選び方

SECURITY.mdには、エージェントやそのトランスクリプトが本番のデータを扱える状態にない場合は、非本番のクラスターを選ぶよう書かれています。実運用では次の分け方が使いやすいです。

調べたいこと接続先証明書
インデックスやクエリの書き方の検証接続先検証用クラスター証明書データベース単位のRead
タスクの停止、ノード間の状態の確認接続先本番(メタデータ中心の調査)証明書Operator(期間を限る)
実データの確認が要る調査接続先本番の複製、または対象を絞った証明書証明書対象データベースだけのRead

本番へつなぐ場合の権限設計全般はMCPで本番環境に接続する権限設計に、他のデータベースMCPの読み取り専用設定との違いはデータベースMCPサーバーの読み取り専用設定を5製品で比較するにまとめています。MongoDBの場合はMongoDB MCPを本番で使うときの読み取り専用設定が近い構成です。

Claude Desktopで使う

Claude Desktopには、GitHubのリリースからravendb-mcp-<version>.mcpbを取得して入れます。Settings > ExtensionsのAdvanced settingsにある「Install Extension…」からファイルを選びます。バンドルにはWindows・macOS・Linuxの実行ファイルが入っていて、クラスターのURL、証明書のパス、パスワードを入力画面で聞かれるため、Nodeも.NETも用意せずに済みます。

設定ファイルで手動登録する場合は、claude_desktop_config.jsonのmcpServersにnpx -y @ravendb/mcpとRAVENDB_URLSを書き、再起動します。Windowsでパスを書くときは、バックスラッシュを\\にエスケープしてください。

つまずいたときの切り分け

症状原因と対処
起動時にAt least one RavenDB URL must be configured原因と対処RAVENDB_URLSも--configのURLも空です。どちらかを設定します
接続に失敗する原因と対処URLに届かない、httpとhttpsの取り違え、証明書のパスや権限の不備のどれかです
登録してもツールが出ない原因と対処新しいセッションを開始します
認証つきクラスターに拒否される原因と対処証明書の権限が足りないか、期限切れです。対象データベースのRead、またはサーバー全体用のOperatorを使います
Windowsのパスでエラーが出る原因と対処JSON内のバックスラッシュを\\にします

サーバーはログを標準エラー出力に書きます(標準出力はJSON-RPC専用)。起動や接続のメッセージは、Claude Code側のMCPサーバーのログで確かめます。

まとめ

RavenDB MCPで安全に手が入るのは「変更の防止」までで、データの流出を防ぐ仕組みはツールの外側にあります。接続文字列の秘密はマスクされても、ログとデバッグパッケージは素のまま返ります。実データもコンテキストに入ります。

そのため、役割を3層に分けると運用が安定します。証明書の権限で見える範囲を決め、permissionsで呼べるツールを決め、CLAUDE.mdで調べ方の作法を決めます。このうち確実に効くのは前の2つです。まず開発用クラスターにRead権限の証明書で登録し、診断の流れが固まってから本番へ広げるのが現実的な順序です。

Langfuseのようにトレースやプロンプトを読ませる別のMCPとの併用なら、ClaudeにLangfuse MCPをつないでプロンプトとトレースを読むの構成が参考になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →