neo4j-mcp-skill

Neo4j MCP スキル

公式 Neo4j MCP サーバーをインストールして設定し、AI エージェントが MCP 互換クライアントを通じて Neo4j に接続できるようにします。

使用する場面

• Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Kiro、その他のエディターを MCP 経由で Neo4j に接続する
• neo4j-mcp-serverをインストールし、特定のエディター用に正しい設定を記述する
• stdio と HTTP トランスポートを切り替える
• 書き込みアクセス（NEO4J_READ_ONLY）を有効または無効にする
• 「MCP server not found」や接続エラーをトラブルシューティングする

使用しない場面

• Cypher クエリの作成や最適化 → neo4j-cypher-skillを使用してください
• 新しい Neo4j Aura インスタンスのプロビジョニング → neo4j-aura-provisioning-skillを使用してください
• エージェントの長期記憶 → neo4j-agent-memory-skillを使用してください
• neo4j-admin / cypher-shell / aura-cli → neo4j-cli-tools-skillを使用してください

---

利用可能な MCP ツール

ツール	種類	内容
get-schema	読み取り	ラベル、リレーションシップタイプ、プロパティキー、インデックスを返します
read-cypher	読み取り	読み取り専用の Cypher（MATCH、RETURN、SHOW）を実行します
write-cypher	書き込み	書き込み用 Cypher（MERGE、CREATE、SET、DELETE）を実行します — NEO4J_READ_ONLY=trueの場合は無効になります
list-gds-procedures	読み取り	利用可能な Graph Data Science プロシージャを一覧表示します（GDS プラグインが必要です）

---

インストール

ステップ 1 — インストールして絶対パスを確認する

# Option A: pip (recommended)
pip install neo4j-mcp-server

# Option B: Download binary
# https://github.com/neo4j/mcp/releases -- macOS, Linux, Windows binaries

# Option C: Docker
docker pull neo4j/mcp

絶対パスを取得します — ステップ 3 で必要になります：

which neo4j-mcp          # e.g. /usr/local/bin/neo4j-mcp
                         # or:  /Users/you/project/.venv/bin/neo4j-mcp  (if installed in venv)

neo4j-mcp --version      # confirm it runs

絶対パスが重要な理由：エディター（Claude Code、Cursor、Claude Desktop）は、独自の制限された PATH を使って MCP サーバーをサブプロセスとして起動します。シェルの PATH は使用しません。macOS では、GUI アプリは .zshrc や .zprofile を引き継ぎません。コマンドに neo4j-mcp を指定すると、何も表示されずに失敗しますが、/full/path/to/neo4j-mcp を指定すれば常に動作します。以下の command フィールドには、必ず which neo4j-mcp の出力を使用してください。

ステップ 2 — 認証情報を準備する

# .env (gitignored)
NEO4J_URI=neo4j+s://<instance>.databases.neo4j.io   # Aura
# or bolt://localhost:7687                           # local
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=<password>
NEO4J_DATABASE=neo4j

エディターを設定する前に、接続を確認してください：

source .env
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" \
  "RETURN 'connected' AS status"
# If cypher-shell not available: python3 -c "
# from neo4j import GraphDatabase, __version__
# d = GraphDatabase.driver('$NEO4J_URI', auth=('$NEO4J_USERNAME','$NEO4J_PASSWORD'))
# d.verify_connectivity(); print('connected'); d.close()"

ステップ 3 — エディターを設定する

使用するエディターの設定ブロックを選択してください。すべて STDIO トランスポートを使用します（MCP サーバーはエディターのサブプロセスとして実行されます）。

Claude Code — ~/.claude/settings.jsonに追加します。ファイルがすでに存在する場合は、neo4jブロックを既存のmcpServersオブジェクトに統合してください。ファイル全体を置き換えないでください。

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

CLI での代替方法（コマンドのみを設定します — 環境変数は引き続きファイルに追加する必要があります）：

claude mcp add neo4j /full/path/to/neo4j-mcp

Claude Desktop

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "neo4j+s://<host>",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<password>",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

VS Code — .vscode/mcp.json（注意：mcpServersではなくserversを使用します。他のすべてのエディターとは異なります）：

{
  "servers": {
    "neo4j": {
      "type": "stdio",
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Cursor — グローバル：~/.cursor/mcp.json / プロジェクト：.cursor/mcp.json（Claude Code と同じ構造で、mcpServersを使用します）。

Windsurf — グローバル：~/.codeium/windsurf/mcp_config.json / プロジェクト：.windsurf/mcp_config.json（Claude Code と同じ構造で、mcpServersを使用します）。

Kiro — グローバル：~/.kiro/settings/mcp.json / プロジェクト：.kiro/settings/mcp.json。エディターの起動前にシェル環境にエクスポートされた値を取得するため、${VARIABLE}をサポートしています：

{
  "mcpServers": {
    "neo4j": {
      "command": "/full/path/to/neo4j-mcp",
      "env": {
        "NEO4J_URI": "${NEO4J_URI}",
        "NEO4J_USERNAME": "${NEO4J_USERNAME}",
        "NEO4J_PASSWORD": "${NEO4J_PASSWORD}",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_READ_ONLY": "true"
      }
    }
  }
}

Cline — ~/.vscode/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json（Claude Code と同じ構造で、mcpServersを使用します）。または、VS Code の設定 → Cline 拡張機能 → MCP Servers パネルから追加します。

Antigravity — プロジェクトルートのmcp_config.json（Claude Code と同じ構造で、mcpServersを使用します）。

ステップ 4 — エディターを再起動する

設定ファイルを編集した後、エディターを再起動してください（または、エディターがホットリロードをサポートしている場合は MCP サーバーを再読み込みしてください）。エディターの MCP パネルまたはツール一覧にサーバーが表示されることを確認してください。

ステップ 5 — スモークテスト

エージェント経由または MCP 経由で get-schema を実行します。「ラベルが返されるか」をテストに使わないでください — データベースが空の場合、ラベルは返されず、接続が壊れている場合と見分けがつきません。

代わりに、空の DB でも成功する次のコマンドを使います。

read-cypher: RETURN 'connected' AS status

期待される結果：{ "status": "connected" }。どのような結果でも、サーバーが稼働しており、認証情報が有効であることを確認できます。

データベースにデータがある場合は、次のコマンドも実行します。

get-schema

期待するノードラベルとリレーションシップタイプが返されることを確認します。

---

HTTP トランスポート

HTTP トランスポートでは、MCP サーバーを常時稼働するネットワークサービスとして実行します。共有サーバー、コンテナー、複数のクライアントで使用する場合に便利です。

# With credentials baked in (simpler — server authenticates all clients as the same user)
neo4j-mcp \
  --neo4j-transport-mode http \
  --neo4j-http-host 127.0.0.1 \
  --neo4j-http-port 8080 \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password <password> \
  --neo4j-database neo4j

HTTP 用のエディター設定（設定に認証情報は含めません。サーバー側で保持します）：

{
  "mcpServers": {
    "neo4j-http": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

リクエストごとの認証（サーバーコマンドから --neo4j-username／--neo4j-password を省略する場合）：各クライアントリクエストに Authorization: Basic <base64(username:password)> ヘッダーを含める必要があります。次のコマンドで値を生成します。

echo -n "neo4j:<password>" | base64

次に、エディター設定に追加します。

{
  "headers": { "Authorization": "Basic bmVvNGo6cGFzc3dvcmQ=" }
}

セキュリティ：0.0.0.0 ではなく、127.0.0.1 にバインドしてください。リモートアクセスが必要で、前段に TLS と認証を用意している場合に限り、より広いインターフェースに変更してください。

---

環境変数

変数	必須	デフォルト	備考
NEO4J_URI	はい	—	Aura では neo4j+s://、ローカルでは bolt://
NEO4J_USERNAME	はい	—
NEO4J_PASSWORD	はい	—
NEO4J_DATABASE	いいえ	サーバーのデフォルト	誤った DB へのルーティングを避けるため、明示的に指定してください
NEO4J_READ_ONLY	いいえ	false	true に設定すると write-cypher が非表示になります（探索時の安全なデフォルト）

NEO4J_READ_ONLY=false に設定する場合（または変数を削除する場合）：データの書き込みが必要なユースケース（インポート、MERGE、スキーマ変更、GDS の書き戻しなど）です。書き込みアクセスがない場合、エージェントに表示されるツールは 3 つ（get-schema、read-cypher、list-gds-procedures）のみとなり、write-cypher の呼び出しは失敗します。

---

APOC の要件

MCP サーバーはスキーマのイントロスペクション（get-schema）に APOC を使用します。Aura では APOC が自動的に含まれています。セルフマネージドの Neo4j では、APOC プラグインをインストールし、許可リストに追加してください。

# neo4j.conf
dbms.security.procedures.unrestricted=apoc.*

確認方法：read-cypher: RETURN apoc.version() AS v — これが失敗すると、get-schema の結果が不完全になります。

---

トラブルシューティング

症状	考えられる原因	対処方法
エディターにサーバーが表示されない	設定ファイルのパスが間違っている、JSON の形式が正しくない、またはエディターが再起動されていない	JSON を検証します（python3 -m json.tool settings.json）。使用しているエディターに対応するファイルを確認し、エディターを再起動します
neo4j-mcp: command not found	エディターの PATH にバイナリの場所が含まれていない	command に絶対パスを指定します。ターミナルで which neo4j-mcp を実行し、結果を貼り付けます
サーバーが起動後すぐに終了する	Python が見つからない（pip install）か、OS に合わないバイナリが使われている（バイナリインストール）	ターミナルでコマンドを手動実行してエラーを確認します：/full/path/neo4j-mcp --version
AuthenticationException	認証情報が間違っている	設定を編集する前に、cypher-shell またはドライバーで URI と認証情報を確認します
write-cypher ツールが見つからない	NEO4J_READ_ONLY=true	書き込みが必要な場合は、変数を削除するか false に設定します
ServiceUnavailable	エディタープロセスから DB に接続できない	ファイアウォール、VPN、または Aura インスタンスが一時停止中でないか確認します
list-gds-procedures の結果が空	GDS がインストールされていない、または Aura Free を使用している	GDS の使用には Aura Professional／Enterprise、またはプラグインを導入したセルフマネージド環境が必要です

---

チェックリスト

• which neo4j-mcp を実行し、絶対パスを記録しました。これは neo4j-mcp ではなく command に記入します
• エディターの設定を編集する前に、接続を確認しました（RETURN 'connected'）
• 認証情報を Git にコミットしていません。.env は .gitignore に追加されています
• NEO4J_READ_ONLY を意図的に設定しました。データの探索には true、書き込みを行うユースケースには false または未設定にします
• NEO4J_DATABASE を明示的に指定しました
• 対象エディターに適した設定ファイルを使用しています（VS Code では servers、それ以外では mcpServers を使用します）
• 設定は有効な JSON です（保存する前に python3 -m json.tool <file> で検証します）
• 設定変更後にエディターを再起動しました
• スモークテストに合格しました。read-cypher: RETURN 'connected' AS status が結果を返します
• セルフマネージド環境で APOC を利用できます：read-cypher: RETURN apoc.version()

---

参考資料

• MCP サーバーのドキュメント
• MCP の GitHub
• すべての Neo4j MCP サーバー
• GraphAcademy：Neo4j MCP ツールを使った開発