Neo4j MCP サーバー

これは、知識グラフ管理のためのバックエンドストレージとしてNeo4jを使用するメモリ制御プロトコル（MCP）サーバー実装です。グラフデータベース形式で知識を保存および取得するためのstdioベースのインターフェースを提供します。

前提条件

• Python 3.8以上

• Neo4j データベース (ローカルまたはリモート)

• Poetry (Python パッケージ マネージャー)

• Docker と Docker Compose (Neo4j を実行するため)

• Go Task（オプション、タスク自動化用）

Related MCP server: MCP Neo4j Knowledge Graph Memory Server

インストール

1. リポジトリをクローンします。

2. まだインストールしていない場合は、Poetry をインストールしてください。

3. 依存関係をインストールします:

構成

クロードデスクトップ構成

Claude Desktop を実行している Ubuntu ユーザーの場合は、次の Claude デスクトップ構成ファイルに MCP サーバーを追加して構成できます。

設定する前に、スタンドアロン実行可能ファイルをビルドする必要があります。

これによりdist/neo4j_mcp_serverにバイナリが作成されます。設定ファイルのパスを、ビルドされた実行ファイルを指すように更新してください。

設定例はexample_mcp_config.jsonに記載されています。このファイルをコピーして変更することができます。

次に、構成ファイル内のcommandパスを編集して、ビルドした実行可能ファイルを指すようにします。

構成には以下が含まれます。

• サーバー名と説明

• サーバーを起動するコマンド（ビルドされた実行ファイルへのパス）

• 利用可能なツールとそのパラメータ

• 必須フィールドとデータ型

サーバーの実行

タスクの使用（推奨）

Go Task がインストールされている場合は、提供されている Taskfile を使用してサーバーを管理できます。

Docker Composeを直接使用する

1. Neo4j コンテナを起動します。

2. Neo4j の準備ができるまで待ちます (コンテナはdocker psで「正常」と表示されます)

MCPサーバーを直接実行する

次のコマンドでサーバーを起動します。

サーバーは stdio モードで起動し、MCP プロトコル メッセージを受け入れる準備が整います。

利用可能なツール

1. エンティティを作成する

ナレッジグラフに新しいエンティティを作成します。各エンティティにはタイプとプロパティが必要です。IDは、明示的に指定されていない場合は、nameプロパティから自動的に設定されます。

パラメータ:

• entities : エンティティ オブジェクトのリスト。各オブジェクトには次のものが含まれます。

  • type : 文字列 - エンティティの種類（例：Person、Organization）

  • properties : オブジェクト - エンティティプロパティのキーと値のペア（「id」または「name」のいずれかを含める必要があります）

入力例:

2. 関係を構築する

ナレッジグラフ内の既存のエンティティ間の関係を作成します。関係を作成する前に、参照されるすべてのエンティティが存在している必要があります。

パラメータ:

• relations : リレーション オブジェクトのリスト。各オブジェクトには次のものが含まれます。

  • type : 文字列 - 関係の種類（例：KNOWS、WORKS_FOR）

  • from : 文字列 - ソースエンティティのID

  • to : 文字列 - 対象エンティティのID

入力例:

3. エンティティを検索する

強力なテキストマッチングとフィルタリング機能を用いて、ナレッジグラフ内のエンティティを検索します。テキストによる検索、タイプ別のエンティティ一覧、特定のプロパティを持つエンティティの検索、あるいはこれらのフィルターの任意の組み合わせが可能です。

パラメータ:

• search_term : 文字列（オプション） - エンティティプロパティで検索するテキスト。指定されていない場合は、他のフィルターに基づいてエンティティが返されます。

• entity_type : 文字列（オプション） - エンティティの種類（例：Person、Organization）で結果をフィルタリングします。単独で指定した場合は、その種類のすべてのエンティティが返されます。

• properties : List[String] (オプション) - フィルタリングするプロパティ名のリスト:

  • search_term を使用: これらのプロパティで用語を検索します

  • search_term がない場合: これらのプロパティのいずれかが定義されているエンティティを返します

• include_relationships : ブール値（オプション、デフォルト: false） - 接続されたエンティティとリレーションシップを含めるかどうか

• fuzzy_match : ブール値（オプション、デフォルト: true） - search_term が指定されている場合に大文字と小文字を区別しない部分一致を使用するかどうか

入力例:

戻り値:

注記:

• フィルタが指定されていない場合は、すべてのエンティティを返します

• エンティティ タイプのフィルタリングは完全一致（あいまい一致ではない）です

• プロパティの存在チェックはIS NOT NULLで行われます

• テキスト検索は、fuzzy_match が true の場合、大文字と小文字を区別しない部分一致をサポートします。

• 空の結果はエラーではなく、空の配列として返されます。

• パフォーマンスに関する考慮事項:

  • 種類によるフィルタリングはテキスト検索よりも効率的です

  • プロパティの存在チェックが最適化されています

  • すべてのプロパティを検索する代わりに、特定のプロパティを使用することを検討してください

  • 将来のバージョンでは、大きな結果セットがページ分けされる可能性があります。

4. エンティティの更新

ナレッジグラフ内の既存のエンティティを更新します。プロパティとラベルの追加/削除をサポートします。

パラメータ:

• updates : 更新オブジェクトのリスト。各オブジェクトには次のものが含まれます。

  • id : 文字列（必須） - 更新するエンティティのID

  • properties : オブジェクト（オプション） - 更新または追加するプロパティ

  • remove_properties : List[String] (オプション) - 削除するプロパティ名

  • add_labels : List[String] (オプション) - エンティティに追加するラベル

  • remove_labels : List[String] (オプション) - エンティティから削除するラベル

入力例:

5. エンティティを削除する

オプションで関係のカスケード削除を使用して、ナレッジ グラフからエンティティを削除します。

パラメータ:

• entity_ids : List[String] (必須) - 削除するエンティティIDのリスト

• cascade : ブール値（オプション、デフォルト: false） - 接続された関係を削除するかどうか

• dry_run : ブール値 (オプション、デフォルト: false) - 変更を加えずに削除の影響をプレビューします

入力例:

戻り値:

• success : ブール値 - 操作が成功したかどうか

• deleted_entities : 削除されたエンティティのリスト

• deleted_relationships : 削除された関係のリスト

• errors : エラーメッセージのリスト（ある場合）

• impacted_entities : 影響を受けるエンティティのリスト（dry_run のみ）

• impacted_relationships : 影響を受ける関係のリスト（dry_run のみ）

6. スキーマのイントロスペクト

ノード ラベル、関係タイプ、それらのプロパティなど、Neo4j データベース スキーマに関する包括的な情報を取得します。

パラメータ: 不要

戻り値:

• schema : 次のものを含むオブジェクト:

  • node_labels : データベース内のすべてのノードラベルのリスト

  • relationship_types : すべての関係タイプのリスト

  • node_properties : ラベルとプロパティ名のリストのマップ

  • relationship_properties : 関係タイプとプロパティ名のリストのマップ

入力例:

テスト

テストスクリプト

このプロジェクトには、システムのさまざまな側面に対するいくつかのテスト スクリプトが含まれています。

1. mcp_neo4j_knowledge_graph/test_mcp_client.py - MCP クライアント機能をテストします

   • サーバーの起動を確認する

   • テストツール一覧

   • スキーマイントロスペクションをテストする

   • エンティティ作成テスト GXP18

2. mcp_neo4j_knowledge_graph/test_mcp_config.py - MCP 構成をテストします

   • 構成ファイルの読み込みを検証します

   • 公式MCP SDKを使用してサーバー接続をテストします

   • 必要なツールがすべて利用可能であることを確認します GXP19

3. mcp_neo4j_knowledge_graph/test_neo4j_connection.py - Neo4j データベース接続をテストします

   • データベースの接続性を検証する

   • 基本的なクエリ機能をテストします

   • 環境設定をチェックする GXP20

テストの実行

テストはいくつかの方法で実行できます。

1. すべてのテストをまとめて実行します。

   task test # Runs all tests including pytest and integration tests

2. 個別のテスト タイプを実行します。

   task test-client # Run MCP client test task test-config # Run MCP config test task test-db # Run Neo4j connection test task test-integration # Run integration tests

3. pytest で直接テストを実行します。

   poetry run pytest # Run all pytest-compatible tests

発達

タスクの使用

このプロジェクトには、いくつかの開発タスクが含まれます。

直接実行

このプロジェクトでは、Poetry とともに自動的にインストールされるいくつかの開発ツールを使用します。

• コードフォーマット用のblack

• インポートソート用のisort

• 糸くず除去用flake8

• テスト用のpytest

Poetry を使用してこれらのツールを実行できます。

エラー処理

サーバーには、次の包括的なエラー処理が含まれています。

• データベース接続の問題

• 無効なクエリ

• 欠落ノード

• 無効なリクエスト形式

• スキーマ検証エラー

• 関係構築の失敗

• エンティティ更新の競合

すべてのエラーは、MCP プロトコル形式の適切なエラー メッセージとともに返されます。

Dockerの設定

Neo4j コンテナは次の設定で構成されます。

• ポート: 7474 (HTTP) および 7687 (Bolt)

• デフォルトの資格情報: neo4j/password

• APOCプラグインが有効

• ファイルのインポート/エクスポートが有効

• ヘルスチェックが設定されました

これらの設定はdocker-compose.ymlファイルで変更できます。

タスクコマンドリファレンス

• task - 利用可能なタスクを表示

• task run - DockerとMCPサーバーを起動する

• task dev - 開発環境（Docker + サーバー + テスト）を起動する

• task docker - Neo4j データベースを起動する

• task server - MCPサーバーを実行する

• task test - すべてのテストを実行する

• task test-client - MCP クライアントテストを実行する

• task test-config - MCP 構成テストを実行する

• task test-db - データベーステストを実行する

• task test-integration - 統合テストを実行する

• task down - すべてのDockerサービスを停止します

• task format - blackとisortを使ったコードのフォーマット

• task lint - flake8 linter を実行する

• task help - すべてのタスクの詳細なヘルプを表示します