Claude Media
ClaudeからNeo4j MCPサーバーでグラフDBに問い合わせる手順
Claude CodeMCPClaude連携チュートリアル

ClaudeからNeo4j MCPサーバーでグラフDBに問い合わせる手順

Neo4j公式のMCPサーバーをClaude Codeに登録し、スキーマ取得と読み取りCypherを試す手順です。読み取り専用モードの効き方と変数名の食い違いも扱います。

読了目安 約11分

Neo4jは、neo4j/mcpという名前でMCPサーバーを公開しています。Claudeのようなクライアントから、グラフのスキーマを調べ、Cypherクエリを実行させるための橋渡し役です。Claude Codeにはclaude mcp addで登録できます。

最初に決めたいのは、書き込みを許すかどうかです。このサーバーは既定で書き込み用のツールも公開するため、NEO4J_READ_ONLY=trueを付けるか付けないかで、Claudeにできることが大きく変わります。以降は導入、各ツールの守備範囲、読み取り専用の効き方、つまずきやすい点の順に進めます。

Neo4j MCPサーバーとは何か

Neo4j MCPは、MCPに対応したクライアントと、Neo4jのインスタンスをつなぐサーバーです。導入ページには、Claude、Cursor、MCP対応のVS Codeが例として挙がっています。MCPはAIに限らない規格なので、モデルを介さないアプリからも接続できます。

公開されるツールは4つです。

ツール読み取り専用役割
get-schema読み取り専用はい役割ラベル、関係タイプ、プロパティキーを調べる
read-cypher読み取り専用はい役割読み取りモードでCypherを実行する
write-cypher読み取り専用いいえ役割書き込みモードでCypherを実行する
list-gds-procedures読み取り専用はい役割GDSのプロシージャを一覧する

動かすための前提は2つあります。1つはNeo4jのインスタンスで、Aura、Neo4j Desktop、自前運用のいずれでも構いません。もう1つは、そのインスタンスに入れたAPOCプラグインです。

GDS(Graph Data Science)は必須ではありません。入っていなければ、サーバーは起動したうえでlist-gds-proceduresなどGDS関連のツールだけを無効にします。ほかのツールはそのまま使えます。

インストールとClaude Codeへの登録

入手方法は3通りあります。

pip install neo4j-mcp-server
brew install neo4j-mcp

3つ目はリリースページからOS向けのアーカイブを落とし、neo4j-mcpをPATHの通った場所に置く方法です。Mac・Linuxならchmod +xして/usr/local/bin/へ移します。入れたあとは次のコマンドでバージョンが出れば完了です。

neo4j-mcp -v

Claude Codeへの登録は、stdioサーバーとして行います。接続情報は環境変数で渡します。

claude mcp add --transport stdio neo4j \
  --env NEO4J_URI=bolt://localhost:7687 \
  --env NEO4J_USERNAME=neo4j \
  --env NEO4J_PASSWORD=your-password \
  --env NEO4J_READ_ONLY=true \
  -- neo4j-mcp

--より前がClaude Code側のオプション、後ろがサーバーを起動するコマンドです。--envの直後にサーバー名を置くと、名前まで環境変数の組として読まれてしまいます。上の例のようにサーバー名を先に書いておけば避けられます。

pipで入れた場合は、起動コマンドがpython -m neo4j_mcp_serverになります。コマンド部分を差し替えてください。

登録後はClaude Code内で/mcpを開き、neo4jが接続済みで、ツール数が表示されているかを確かめます。接続に失敗したときの詳しい手順はMCPサーバーを一括再接続する方法にあります。

Claude Desktopを使う場合も考え方は同じです。設定ファイルのmcpServersに、command・args・envを書く形です。envにはこの記事と同じ環境変数を入れます。

最初の質問で動作を確かめる

導入ページには、試す質問の例が3つ載っています。

  • Neo4jのインスタンスに何が入っているか。ノードラベル、関係タイプ、プロパティキーを一覧して
  • Personノードとその関係をすべて探して
  • 名前が「John」のUserノードを作って

3つ目は書き込みです。読み取り専用で登録していれば、write-cypherがClaudeに見えないため実行されません。まず1つ目を投げて、スキーマが返ることを確認するのが順当です。

get-schemaは、NEO4J_SCHEMA_SAMPLE_SIZE個のノードを標本にしてスキーマを推定します。既定は100です。スキーマは全件の走査ではなく標本からの推定なので、気になるラベルは取得結果を実データと見比べてください。

読み取りと書き込みの境界

境界を決めるのは、NEO4J_READ_ONLYとread-cypherの判定の2つです。

読み取り専用モードで消えるもの

NEO4J_READ_ONLYをtrueにすると、write-cypherのような書き込みツールはクライアントに公開されません。コマンドラインフラグ--neo4j-read-only trueでも切り替えられ、両方が指定されたときはフラグが優先されます。

注意したいのは、管理系のクエリも道連れになる点です。SHOW USERSやSHOW DATABASESはread-cypherでは実行できず、write-cypherを使う決まりです。読み取り専用モードのままでは、これらをClaudeに実行させる手段がありません。

read-cypherが拒否するもの

read-cypherは、実行前にデータベースへ1往復して、クエリが読み取りかどうかを確かめます。拒否の対象は次のとおりです。

  • CREATE、MERGE、DELETE、SETなどの書き込み
  • CREATE INDEX、DROP CONSTRAINTなどのスキーマ操作
  • SHOW USERSなどの管理系クエリ
  • PROFILEを含むクエリ(EXPLAIN PROFILEも同様)

判定はEXPLAINとNeo4jのクエリ種別の分類に頼っています。READMEには、読み取り専用と誤って分類されたカスタムのプロシージャや関数は、このチェックをすり抜ける場合があるとの注記があります。直すのはプロシージャの作者の責任だと書かれています。

つまりread-cypherは、Cypherの構文を見て止めているわけではありません。独自のプロシージャを多用するデータベースでは、「読み取り専用」の一言を鵜呑みにしないほうが安全です。

設定でつまずきやすい点

変数名が2種類ある

READMEのVS Code向け設定例は、NEO4J_MCP_URI、NEO4J_MCP_USERNAME、NEO4J_MCP_READ_ONLYのようにNEO4J_MCP_を頭に付けた名前を使っています。一方、設定リファレンスの表はNEO4J_URI、NEO4J_USERNAME、NEO4J_READ_ONLYです。

どちらが正かは、この2つのページだけでは決められません。設定リファレンスの表には、--neo4j-uriのように対応するコマンドラインフラグも並んでいます。表に載っている名前を使い、動かないときはフラグで同じ値を渡して切り分けるのが確実です。

stdioとHTTPで資格情報の扱いが逆になる

既定のトランスポートはSTDIOで、ユーザー名とパスワードは環境変数で渡します。起動時には、接続とAPOCの有無が検証されます。

NEO4J_TRANSPORT_MODE=httpにすると、サーバーはステートレスになり、資格情報はリクエストごとのBearerトークンまたはBasic認証で受け取ります。このモードではNEO4J_USERNAMEとNEO4J_PASSWORDを設定してはいけません。チームで共有する用途ならHTTP、手元の1人利用ならSTDIOと分けて考えると整理できます。

HTTPモードの待ち受けは既定で127.0.0.1です。TLSを使う場合は、証明書と秘密鍵のファイルを指定します。

環境変数をサーバーに渡しすぎない

stdioサーバーには、環境変数としてパスワードを渡します。Claude Codeが既定で引き継ぐ環境が広いと、関係のない変数まで届きます。渡す変数を絞る設定はCLAUDE_CODE_MCP_ALLOWLIST_ENVの解説にまとまっています。

接続先データベース・テレメトリー・ログの設定

設定リファレンスの表には、ここまでの変数のほかに次の4つが載っています。

環境変数フラグ既定用途
NEO4J_DATABASEフラグ--neo4j-database既定neo4j用途接続するデータベース名
NEO4J_TELEMETRYフラグ--neo4j-telemetry既定true用途falseでテレメトリーを無効にする
NEO4J_LOG_LEVELフラグ--neo4j-log-level既定info用途ログの詳細度
NEO4J_LOG_FORMATフラグ--neo4j-log-format既定text用途ログの形式(textかjson)

複数のデータベースを持つインスタンスでは、NEO4J_DATABASEを指定しないと既定のneo4jに接続します。業務用のデータベースが別名なら、--env NEO4J_DATABASE=<名前>を登録コマンドに足してください。テレメトリーは既定で有効なので、送りたくない環境では--env NEO4J_TELEMETRY=falseを付けます。

Claude側で守らせる運用

サーバー側の制限に加えて、Claude Code側でも歯止めを二重にかけられます。

書き込みツールを権限で止める

write-cypherを権限ルールで拒否しておくと、サーバー側の設定が変わっても、Claude Codeからの呼び出しを止められます。

{
  "permissions": {
    "deny": ["mcp__neo4j__write-cypher"]
  }
}

ルールはサーバー名とツール名をつなげたmcp__<サーバー名>__<ツール名>の形です。上の例は、登録名がneo4jのときの書き方です。

CLAUDE.mdに手順を書く

グラフDBでは、ラベルや関係タイプを知らないままCypherを書くと外れます。スキーマ取得を先にやらせる規約をCLAUDE.mdに置いておきます。

## Neo4jの扱い
 
- Cypherを書く前に、必ずget-schemaでラベルと関係タイプを確認する
- MATCHにはLIMITを付け、件数が不明なときはまずcount(*)で数える
- write-cypherは使わない。更新が必要なときは提案だけして止まる

LIMITの指示には理由があります。Claude Codeは、MCPツールの出力が10,000トークンを超えると警告を出し、既定では25,000トークンで出力を切ります。ノードやパスを無制限に返すクエリは、この上限に当たりやすくなります。

生成クエリを実行前に見せる

read-cypherが通る範囲でも、重いクエリは本番の負荷になります。実行前にCypherをチャットに表示させ、確認してから流すよう指示しておけます。

つながらないときの切り分け

接続に失敗したら、次の順で見ます。

手順

接続失敗の切り分け

  1. 1

    サーバー単体で起動する

    同じ環境変数を付けてneo4j-mcpを直接実行し、起動時の検証で落ちていないかを見ます。接続できないときと、APOCが見つからないときは、ここで気づけます。

  2. 2

    変数名を確かめる

    NEO4J_URI系とNEO4J_MCP_URI系のどちらを渡したかを確認します。決め手がなければ、コマンドラインフラグで同じ値を渡してみます。

  3. 3

    Claude Code側の状態を見る

    claude mcp get neo4jで失敗の詳細を確認し、/mcpから再接続します。

NEO4J_URIは必須の設定で、例として載っているのはbolt://localhost:7687です。設定リファレンスに載っている接続URIの例はこの1つだけで、Auraなどのクラウド側のインスタンス向けの書式は載っていません。接続先がクラウドの場合は、そのサービスが示す接続URIを入れ、手順1の単体起動で通るか試してください。

他のDB用MCPサーバーとの違い

リレーショナルDB向けの手順は、PostgreSQL MCPサーバーの使い方とMySQL MCPサーバーの使い方にあります。違いは、問い合わせの言語と、スキーマの形です。SQLの表と違い、グラフにはラベルと関係タイプがあり、Claudeに探索を任せるならget-schemaの結果が出発点になります。

まとめ

導入そのものは数分で済みます。時間をかけたいのは、書き込みを許すかどうかの設計です。読み取り専用で登録し、write-cypherを権限で拒否し、CLAUDE.mdにスキーマ確認の規約を置く。この3点があれば、グラフへの自然言語の問い合わせを、手元のデータを壊さずに試せます。そのうえで、独自のプロシージャを持つデータベースではread-cypherの判定にも限界があることを頭に置いてください。

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

関連する記事

Claude Code をもっと見る →