Neo4j MCP サーバー

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

前提条件

Python 3.8以上
Neo4j データベース (ローカルまたはリモート)
Poetry (Python パッケージマネージャー)
Docker と Docker Compose (Neo4j を実行するため)
Go Task（オプション、タスク自動化用）

インストール

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

git clone <repository-url>
cd neo4j_mcp_server

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

curl -sSL https://install.python-poetry.org | python3 -

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

poetry install

構成

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

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

~/.config/Claude/claude_desktop_config.json

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

task build

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

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

cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json

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

{
  "mcpServers": [
    {
      "name": "neo4j-knowledge-graph",
      "command": ["/path/to/your/dist/neo4j_mcp_server"],
      ...
    }
  ]
}

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

サーバー名と説明
サーバーを起動するコマンド（ビルドされた実行ファイルへのパス）
利用可能なツールとそのパラメータ
必須フィールドとデータ型

サーバーの実行

タスクの使用（推奨）

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

# Show available tasks
task

# Start everything (Docker + Server)
task run

# Start development environment (Docker + Server + Test)
task dev

# Stop all services
task down

Docker Composeを直接使用する

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

docker-compose up -d

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

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

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

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

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

利用可能なツール

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

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

パラメータ:

entities : エンティティオブジェクトのリスト。各オブジェクトには次のものが含まれます。
- type : 文字列 - エンティティの種類（例：Person、Organization）
- properties : オブジェクト - エンティティプロパティのキーと値のペア（「id」または「name」のいずれかを含める必要があります）

入力例:

{
    "entities": [{
        "type": "Person",
        "properties": {
            "name": "John Doe",
            "occupation": "Developer",
            "age": 30
        }
    }]
}

2. 関係を構築する

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

パラメータ:

relations : リレーションオブジェクトのリスト。各オブジェクトには次のものが含まれます。
- type : 文字列 - 関係の種類（例：KNOWS、WORKS_FOR）
- from : 文字列 - ソースエンティティのID
- to : 文字列 - 対象エンティティのID

入力例:

{
    "relations": [{
        "type": "KNOWS",
        "from": "john_doe",
        "to": "jane_smith"
    }]
}

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

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

パラメータ:

search_term : 文字列（オプション） - エンティティプロパティで検索するテキスト。指定されていない場合は、他のフィルターに基づいてエンティティが返されます。
entity_type : 文字列（オプション） - エンティティの種類（例：Person、Organization）で結果をフィルタリングします。単独で指定した場合は、その種類のすべてのエンティティが返されます。
properties : List[String] (オプション) - フィルタリングするプロパティ名のリスト:
- search_term を使用: これらのプロパティで用語を検索します
- search_term がない場合: これらのプロパティのいずれかが定義されているエンティティを返します
include_relationships : ブール値（オプション、デフォルト: false） - 接続されたエンティティとリレーションシップを含めるかどうか
fuzzy_match : ブール値（オプション、デフォルト: true） - search_term が指定されている場合に大文字と小文字を区別しない部分一致を使用するかどうか

入力例:

// Search by text with type filter
{
    "search_term": "John",
    "entity_type": "Person",
    "properties": ["name", "occupation"],
    "include_relationships": true
}

// List all entities of a type
{
    "entity_type": "Person"
}

// Find entities with specific properties
{
    "properties": ["email", "phone"],
    "entity_type": "Contact"
}

// Combine filters
{
    "entity_type": "Person",
    "properties": ["email"],
    "search_term": "example.com",
    "fuzzy_match": true
}

// Return all entities (no filters)
{}

戻り値:

{
    "results": [
        {
            "id": "john_doe",
            "type": ["Entity", "Person"],
            "properties": {
                "name": "John Doe",
                "email": "john@example.com"
            },
            "relationships": [  // Only included if include_relationships is true
                {
                    "type": "WORKS_AT",
                    "direction": "outgoing",
                    "node": {
                        "id": "tech_corp",
                        "type": "Company",
                        "properties": {
                            "name": "Tech Corp"
                        }
                    }
                }
            ]
        }
    ]
}

注記:

フィルタが指定されていない場合は、すべてのエンティティを返します
エンティティタイプのフィルタリングは完全一致（あいまい一致ではない）です
プロパティの存在チェックはIS NOT NULLで行われます
テキスト検索は、fuzzy_match が true の場合、大文字と小文字を区別しない部分一致をサポートします。
空の結果はエラーではなく、空の配列として返されます。
パフォーマンスに関する考慮事項:
- 種類によるフィルタリングはテキスト検索よりも効率的です
- プロパティの存在チェックが最適化されています
- すべてのプロパティを検索する代わりに、特定のプロパティを使用することを検討してください
- 将来のバージョンでは、大きな結果セットがページ分けされる可能性があります。

4. エンティティの更新

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

パラメータ:

updates : 更新オブジェクトのリスト。各オブジェクトには次のものが含まれます。
- id : 文字列（必須） - 更新するエンティティのID
- properties : オブジェクト（オプション） - 更新または追加するプロパティ
- remove_properties : List[String] (オプション) - 削除するプロパティ名
- add_labels : List[String] (オプション) - エンティティに追加するラベル
- remove_labels : List[String] (オプション) - エンティティから削除するラベル

入力例:

{
    "updates": [{
        "id": "john_doe",
        "properties": {
            "occupation": "Senior Developer",
            "salary": 100000
        },
        "remove_properties": ["temporary_note"],
        "add_labels": ["Verified"],
        "remove_labels": ["Pending"]
    }]
}

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

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

パラメータ:

entity_ids : List[String] (必須) - 削除するエンティティIDのリスト
cascade : ブール値（オプション、デフォルト: false） - 接続された関係を削除するかどうか
dry_run : ブール値 (オプション、デフォルト: false) - 変更を加えずに削除の影響をプレビューします

入力例:

{
    "entity_ids": ["john_doe", "jane_smith"],
    "cascade": true,
    "dry_run": true
}

戻り値:

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 : 関係タイプとプロパティ名のリストのマップ

入力例:

{}

テスト

テストスクリプト

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

mcp_neo4j_knowledge_graph/test_mcp_client.py - MCP クライアント機能をテストします
- サーバーの起動を確認する
- テストツール一覧
- スキーマイントロスペクションをテストする
- エンティティ作成テスト GXP18
mcp_neo4j_knowledge_graph/test_mcp_config.py - MCP 構成をテストします
- 構成ファイルの読み込みを検証します
- 公式MCP SDKを使用してサーバー接続をテストします
- 必要なツールがすべて利用可能であることを確認します GXP19
mcp_neo4j_knowledge_graph/test_neo4j_connection.py - Neo4j データベース接続をテストします
- データベースの接続性を検証する
- 基本的なクエリ機能をテストします
- 環境設定をチェックする GXP20

テストの実行

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

すべてのテストをまとめて実行します。
task test # Runs all tests including pytest and integration tests
個別のテストタイプを実行します。
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
pytest で直接テストを実行します。
poetry run pytest # Run all pytest-compatible tests

発達

タスクの使用

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

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

直接実行

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

コードフォーマット用のblack
インポートソート用のisort
糸くず除去用flake8
テスト用のpytest

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

# Format code
poetry run black .

# Sort imports
poetry run isort .

# Run linter
poetry run flake8

# Run tests
poetry run pytest

エラー処理

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

データベース接続の問題
無効なクエリ
欠落ノード
無効なリクエスト形式
スキーマ検証エラー
関係構築の失敗
エンティティ更新の競合

すべてのエラーは、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 - すべてのタスクの詳細なヘルプを表示します

Neo4j Knowledge Graph

Integrations

Neo4j MCP サーバー

前提条件

インストール

構成

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

サーバーの実行

タスクの使用（推奨）

Docker Composeを直接使用する

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

利用可能なツール

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

2. 関係を構築する

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

4. エンティティの更新

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

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

テスト

テストスクリプト

テストの実行

発達

タスクの使用

直接実行

エラー処理

Dockerの設定

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

Appeared in Searches