Neo4j MCP

Claude（およびその他のMCPクライアント）がNeo4jグラフデータベースに対してクエリを実行し、変更を加えることを可能にするModel Context Protocolサーバーです。スタンドアロンのMCPサーバーとして、また一度インストールすればどのプロジェクトからでも再利用できるClaude Codeプラグインとして提供されます。

各プロジェクトはローカルの .env ファイルを通じて独自のNeo4j認証情報を提供するため、Claude Codeを開くフォルダに応じて、同じプラグインで異なるデータベースをターゲットにすることができます。

特徴

• 明示的な read / write モードを備えた統合された cypher_query ツール。

• スキーマのイントロスペクション：ラベル、リレーションシップタイプ、プロパティキー。

• 完全な結果シリアライズ — ノード/リレーションシップの element_id、ラベル、タイプ、およびNeo4jの時間的/空間的値を保持します。

• 切り捨てフラグ付きの結果サイズ制限 — 暴走した MATCH (n) がレスポンスを肥大化させないようにします。

• .env を介したプロジェクトごとの認証情報（作業ディレクトリから python-dotenv によって読み込まれます）。

• stdio（Claude Code、Claude Desktop、Cursor）およびSSEで動作します。

Related MCP server: neo4j-server-remote

前提条件

• Python 3.10+

• 到達可能なNeo4jデータベース（ローカル、Docker、またはAura）

• pip（または uv、pipx）

Pythonパッケージのインストール

このプラグインは neo4j-mcp-server というコンソールスクリプトを呼び出すため、パッケージが最初にPATH上にある必要があります。

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

インストールされたことを確認します：

which neo4j-mcp-server
neo4j-mcp-server --help

ヒント: pipx を使用する場合、pipx install -e . を実行すると、サーバーをグローバルなPython環境から分離した状態に保つことができます。

Claude Codeプラグインとして使用する

このリポジトリには .claude-plugin/plugin.json にプラグインマニフェストが含まれています。ユーザーレベルでインストールすると、neo4j MCPサーバーはすべてのClaude Codeセッション、およびどのプロジェクトでも利用可能になります。

1. プラグインのインストール

Claude Code内から：

/plugin install /absolute/path/to/neo4j-mcp

これでマニフェストがグローバルに登録されます。（公開されている場合はマーケットプレイス経由で追加することも可能です。Claude Codeのプラグインドキュメントを参照してください。）

2. Neo4jと通信するプロジェクトに .env を配置する

MCPサーバーはClaude Codeの作業ディレクトリを継承するため、python-dotenv はそのプロジェクトのルートにある .env を読み取ります。フォルダが異なればデータベースも異なるため、プラグインの再設定は不要です。

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

Aura / 暗号化接続の場合：

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

認証不要のローカルインスタンスの場合は、NEO4J_USERNAME と NEO4J_PASSWORD を空のままにします。

.env をコミットしないでください。 すべてのプロジェクトの .gitignore に追加してください。

3. Claude Codeから使用する

プロジェクトを開き、Claudeに以下のように尋ねます：

• 「このグラフにはどのようなラベルとリレーションシップタイプが存在しますか？」

• 「最も接続数の多い Person ノードを10個見つけてください。」

• 「2010年に公開された Inception というタイトルの Movie ノードを作成してください。」

Claudeは必要に応じて cypher_query、get_database_schema、および test_database_connection ツールを呼び出します。

Claude Codeなしで使用する

同じパッケージを、MCP互換クライアント用の標準的なMCPサーバーとして使用できます。

Claude Desktop / Cursor

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはCursorのMCP設定に追加します：

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "args": []
    }
  }
}

認証情報を設定するには、クライアントがプロセスを起動する場所の隣に .env を配置するか、環境ブロックで NEO4J_* 変数をエクスポートします。

SSEトランスポート（Webクライアント）

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

スタンドアロンCLI

単発のテスト用に小さなクライアントが同梱されています：

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

設定リファレンス

すべての設定は環境変数（または作業ディレクトリ内の .env ファイル）から読み取られます。

MCPサーバーによって公開されるツール

リソース: neo4j://schema, neo4j://connection。プロンプト: cypher_query_help。

開発

pip install -e ".[dev]"
pytest                    # 21 unit tests, no live database needed
ruff check src/ tests/
mypy src/neo4j_mcp/

トラブルシューティング

• Neo4j authentication failed — ユーザー名/パスワードの不一致。認証不要のDBの場合は、両方を空のままにしてください（neo4j/neo4j に設定しないでください）。

• Neo4j service unavailable — DBがダウンしているか、NEO4J_HOST / NEO4J_PORT が間違っています。cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT を実行して確認してください。

• プラグインが neo4j-mcp-server を見つけられない — コンソールスクリプトがClaude Codeの継承するPATH上にありません。pipx でインストールするか、GUIアプリ用にシェルrcファイルが正しい PATH をエクスポートしていることを確認してください。macOSでは、GUIアプリは ~/.zshrc を読み込まないため、launchctl setenv PATH ... を使用するか、/usr/local/bin にインストールしてください。

• 読み取り時に truncated: true となる — 呼び出し時の limit を増やすか、.env で NEO4J_DEFAULT_RESULT_LIMIT を高く設定してください。

MITライセンス。