Neo4j GDS Agent

GDS Agent

GDS Agent を使うと、LLM が Neo4j のグラフデータを対象に推論し、データサイエンスの作業を実行できます。次の 2 つの成果物を使用します。

• ツール — 中心性、コミュニティ検出、経路探索、類似性、ノード埋め込み、ML パイプラインなどの Neo4j Graph Data Science（GDS）アルゴリズムを公開する MCP サーバーです。
• スキル — これらのツールをいつ、どのように使うか、またグラフのデータサイエンスに取り組む際のベストプラクティスをエージェントに教えるエージェントスキル（neo4j-graph-data-scientist）です。

Claude Code、Claude Desktop、claude.ai、OpenAI Codex、Cursor、VS Code/Copilot、Gemini CLI など、MCP に対応したあらゆるハーネスで動作し、エージェントフレームワークからプログラムで利用することもできます。セルフマネージドの Neo4j では GDS プラグインを、AuraDB では GDS Aura Graph Analytics セッションを使用し、STDIO または HTTP トランスポート経由で接続します。

セットアップが完了すると、Neo4j のグラフについてあらゆる質問をして、回答を得られます。エージェントと協力してグラフデータサイエンティストとして複雑な課題を解決できます。

インストール

ハーネス	ツール（MCP）	スキル	ガイド
Claude Code	/plugin marketplace add neo4j-contrib/gds-agent → /plugin install gds-agent@neo4j-gds	プラグインに同梱	セットアップ
Claude Desktop	releases から .mcpb をダウンロードし、ダブルクリック	Settings → Skills からスキルの zip をアップロード	セットアップ
OpenAI Codex	codex mcp add neo4j-gds -- uvx gds-agent	npx skills add neo4j-contrib/gds-agent -a codex	セットアップ
Cursor	ワンクリックバッジ	npx skills add neo4j-contrib/gds-agent -a cursor	セットアップ
VS Code / Copilot	ワンクリックバッジまたは .vscode/mcp.json	npx skills add neo4j-contrib/gds-agent -a copilot	セットアップ
Gemini CLI	gemini extensions install https://github.com/neo4j-contrib/gds-agent	拡張機能に同梱	セットアップ
独自のエージェント	任意の MCP クライアント（stdio/HTTP）	指示として SKILL.md を挿入	セットアップ

ほとんどのローカルセットアップでは、uv のインストールが必要です（サーバーは PyPI から uvx gds-agent を実行して起動します）。汎用 MCP クライアントは、以下の環境変数を設定し、stdio 経由で uvx gds-agent を実行します。

設定リファレンス

環境変数（またはお使いのハーネスのインストーラーの認証情報フォーム）として設定します。

変数	必須	用途
NEO4J_URI	はい	neo4j:// または neo4j+s:// 接続 URI
NEO4J_USERNAME / NEO4J_PASSWORD	はい	データベースの認証情報
NEO4J_DATABASE	いいえ	データベース名（デフォルトは neo4j）
AURA_API_CLIENT_ID / AURA_API_CLIENT_SECRET	セッションモード	Aura Graph Analytics 用の Aura API 認証情報
AURA_API_PROJECT_ID	いいえ	API クライアントが複数のプロジェクトにアクセスできる場合のみ
SESSION_MEMORY_GB / SESSION_TTL_HOURS	いいえ	セッションのデフォルト値（8 GB／12 時間）
SESSION_TIMEOUT_SECONDS	いいえ	セッションが Ready になるまで待機する秒数
GDS_AGENT_MAX_RESULT_ROWS / _CHARS / _CELL_CHARS	いいえ	ツール出力の上限（500／100000／200）

デフォルトでは、サーバーはローカルの MCP クライアント向けに STDIO トランスポートを使用します。HTTP ネイティブのクライアントでは、ストリーム可能な HTTP を使ってサーバーを実行します。

gds-agent --transport http --host 127.0.0.1 --port 8000 --path /mcp

同等の環境変数は GDS_AGENT_TRANSPORT、GDS_AGENT_HOST、GDS_AGENT_PORT、GDS_AGENT_PATH です。Neo4j MCP スタイルの NEO4J_TRANSPORT と NEO4J_MCP_SERVER_* という名前もサポートされています。

GDS Aura Graph Analytics（セッション）

サーバーは、接続先の Neo4j に GDS プラグインがインストールされているか、GDS Aura Graph Analytics セッションを使用するかを検出します。起動時に gds.session.list() を実行して検出し、成功した場合はセッションモードが使用され、グラフのプロジェクションは gds.graph.project.remote にフォールバックします。

セッションモードでは、データベースの認証情報と同じ .env ファイルまたは env ブロックに Aura API 認証情報を設定する必要があります（上記の設定リファレンスを参照してください）。 セッションはエージェントが明示的に管理します。セッションモードでは、追加のツール（list_sessions、create_session、delete_session）が利用可能になります。最初に create_session でセッションを作成する必要があります。その後、project_graph_cypher は必須パラメーター sessionName で指定されたセッションに各グラフをプロジェクションし、アルゴリズムの呼び出しは graphName によって適切なセッションに自動的にルーティングされます。ほとんどのワークフローでは、すべてのグラフを保持する単一のセッションで十分です。複数のセッションを使うと、分析を並行して実行できます。セッションのサイズを変更するには（OOM の発生後など）、セッションを削除してから、より大きな memoryGB を指定して再作成します。サーバーが作成するすべてのセッション名には mcp_ というプレフィックスが付きます。Aura セッションの料金は DB とは別に請求されます。

スキル

[skills/neo4j-graph-data-scientist](skills/neo4j-graph-data-scientist/SKILL.md) は、Claude Code プラグイン、Gemini 拡張機能、npx skills、リリース用スキル zip から、この単一の場所を参照して使用されます。GDS 固有のワークフローのベストプラクティスと、トラブルシューティングのリファレンスガイドに加え、一般的なデータサイエンスのベストプラクティスも扱います。gds-agent と mcp-neo4j-cypher MCP サーバー向けに設計されています。

GDS と併用する読み取り専用 Cypher

GDS サーバーは任意の Cypher を実行しないよう意図的に設計されています。Cypher の唯一のエントリーポイントはグラフのプロジェクションです。エージェントが基盤となるデータも読み取れるようにするには（プロパティの確認、集計、アルゴリズムの結果の検証など）、[mcp-neo4j-cypher](https://github.com/neo4j-contrib/mcp-neo4j) サーバーを読み取り専用モードで併用してください。

Claude Code プラグインとGemini CLI 拡張機能には、すでにこのサーバーが含まれています。インストール時に、同じ認証情報を使って両方のサーバーが設定され、NEO4J_READ_ONLY=true によって書き込みツールが無効になります。NEO4J_RESPONSE_TOKEN_LIMIT は読み取りクエリの応答（トークン数）の上限を設定するため、大きな結果でモデルに過剰な負荷がかかるのを防げます。Cypher 側の上限が不要な場合は省略してください。その他のハーネスでは、gds-agent と並べて 2 つ目のサーバーを登録してください。

"neo4j-cypher": {
  "command": "uvx",
  "args": ["[email protected]", "--transport", "stdio"],
  "env": {
    "NEO4J_URI": "neo4j://localhost:7687",
    "NEO4J_USERNAME": "neo4j",
    "NEO4J_PASSWORD": "<your-password>",
    "NEO4J_READ_ONLY": "true",
    "NEO4J_RESPONSE_TOKEN_LIMIT": "20000"
  }
}

サンプルデータセット

ロンドン地下鉄のサンプルデータセットを読み込むには、次の手順に従ってください。

1. リポジトリをフォークしてクローンします
2. GDS プラグインを含む Neo4j データベースをインストールします： Neo4j Download Center から Neo4j Desktop をダウンロードします Neo4j Desktop から GDS プラグインをインストールします 新しいデータベースを作成して起動します
3. 必要な認証情報を .env ファイルに設定します：

 NEO4J_URI=bolt://localhost:7687  # or your database URI
 NEO4J_USERNAME=neo4j  # or your db username
 NEO4J_PASSWORD=your_password

4. 次のコマンドでロンドン地下鉄のデータセットを読み込みます（uv がスクリプトの依存関係を自動的に解決します）：

 uv run import_data.py --undirected

Neo4j workspace から DB に接続してグラフをクエリすると、次のように表示されます： ロンドン地下鉄のグラフ

開発用サーバーの起動

1. /mcp_server ディレクトリ内で uv sync --dev を実行し、続けて uv run gds-agent を実行して MCP サーバーを単独で起動するか、claude を実行してエージェントを含む claude-cli を起動します。
2. 作業ツリーからプラグイン（MCP サーバー＋スキル）を試すには、リポジトリのルートで claude --plugin-dir . を実行します。

リリース

バージョン番号は scripts/bump_version.py によって pyproject.toml およびすべての配布マニフェスト間で同期されています。v* タグをプッシュすると、リリースワークフローが実行されます。

貢献方法

フォークしたリポジトリのブランチから、このリポジトリの main ブランチにプルリクエストを作成してください。例：mygithubid:add-new-algo -> neo4j-contrib:main。

GitHub Actions の CI ビルドでは、すべてのコードスタイルチェックとテストに合格する必要があります。

ローカルでコードスタイルチェックを実行して修正するには、/mcp_server ディレクトリで次を実行します：

uv sync --dev

Python 環境をセットアップします。次に、

uv run pytest tests -v -s
uv run ruff check
uv run ruff format

すべてのテストとコードスタイルの修正を実行します。

機能リクエストとバグ報告

バグや新機能のリクエストを報告するには、イシューを作成してください。 バグの場合は、完全なスタックトレースとエラーを記載してください。 可能であれば、関連するログを mcp_server_neo4j_gds.log に添付してください。このファイルは、gds エージェントをソースから実行している場合は /mcp_server/src_mcp_server_neo4j_gds ディレクトリ内にあり、Claude の場合はログの保存先（例：Mac の Claude Desktop では /Library/Logs/Claude）にあります。可能であれば、問題を再現するために使用できる最小限の関連データセットも含めてください。

追加リソース

GDS エージェントは、Neo4j のツールを追加で提供するものなど、他の MCP サーバーと併用できます：https://github.com/neo4j-contrib/mcp-neo4j アーキテクチャとベンチマーク結果の詳細を含む Arxiv 論文：https://arxiv.org/abs/2508.20637。