mcp-neo4j-memory

🧠🕸️ Neo4j ナレッジグラフメモリ MCP サーバー

mcp-name: io.github.neo4j-contrib/mcp-neo4j-memory

🌟 概要

Neo4j グラフデータベースとの統合により、永続的なメモリ機能を提供する Model Context Protocol（MCP）サーバーの実装です。

情報をグラフ構造で保存することで、このサーバーはメモリノードとしてエンティティ間の複雑な関係を維持し、複数の会話やセッションにわたってクエリや分析ができる知識の長期保持を可能にします。

Neo4j Aura を使えば、独自のデータベースサーバーを無料でホストしたり、共同作業者と共有したりできます。それ以外の場合は、独自の Neo4j サーバーをローカルで実行できます。

この MCP サーバーは Neo4j のグラフデータベース機能を活用して、外部メモリシステムとして機能する、相互に接続されたナレッジベースを作成します。Cypher クエリを通じて、保存された情報の探索と取得、異なるデータポイント間の関係の分析、蓄積された知識からのインサイトの生成が可能です。このメモリは Claude の機能によってさらに強化できます。

🕸️ グラフスキーマ

• Memory - 名前、タイプ、観察内容を持つエンティティを表すノードです。
• Relationship - 2 つのエンティティ間の、タイプを持つ関係です。

🔍 使用例

Let's add some memories 
I, Michael, living in Dresden, Germany work at Neo4j which is headquartered in Sweden with my colleagues Andreas (Cambridge, UK) and Oskar (Gothenburg, Sweden)
I work in Product Management, Oskar in Engineering and Andreas in Developer Relations.

その結果、Claude は create_entities ツールと create_relations ツールを呼び出します。

📦 コンポーネント

🔧 ツール

サーバーでは、次の主要なツールを提供しています。

🔎 クエリツール

• read_graph

  • ナレッジグラフ全体を読み取ります
  • 入力は不要です
  • 戻り値：エンティティと関係を含む完全なグラフ

• search_nodes

  • クエリに基づいてノードを検索します
  • 入力：
    • query（string）：名前、タイプ、観察内容に一致する検索クエリ
  • 戻り値：一致するサブグラフ

• find_nodes

  • 名前で特定のノードを検索します
  • 入力：
    • names（文字列の配列）：取得するエンティティ名
  • 戻り値：指定したノードを含むサブグラフ

♟️ エンティティ管理ツール

• create_entities

  • ナレッジグラフに複数の新しいエンティティを作成します
  • 入力：
    • entities：次の内容を含むオブジェクトの配列：
      • name（string）：エンティティの名前
      • type（string）：エンティティのタイプ
      • observations（文字列の配列）：エンティティに関する初期の観察内容
  • 戻り値：作成されたエンティティ

• delete_entities

  • 複数のエンティティと、それに関連付けられた関係を削除します
  • 入力：
    • entityNames（文字列の配列）：削除するエンティティの名前
  • 戻り値：成功確認

🔗 関係管理ツール

• create_relations

  • エンティティ間に複数の新しい関係を作成します
  • 入力：
    • relations：次の内容を含むオブジェクトの配列：
      • source（string）：ソースエンティティの名前
      • target（string）：ターゲットエンティティの名前
      • relationType（string）：関係のタイプ
  • 戻り値：作成された関係

• delete_relations

  • グラフから複数の関係を削除します
  • 入力：
    • relations：create_relations と同じスキーマのオブジェクトの配列
  • 戻り値：成功確認

📝 観察内容の管理ツール

• add_observations

  • 既存のエンティティに新しい観察内容を追加します
  • 入力：
    • observations：次の内容を含むオブジェクトの配列：
      • entityName（string）：追加先のエンティティ
      • contents（文字列の配列）：追加する観察内容
  • 戻り値：追加された観察内容の詳細

• delete_observations

  • エンティティから特定の観察内容を削除します
  • 入力：
    • deletions：次の内容を含むオブジェクトの配列：
      • entityName（string）：削除元のエンティティ
      • observations（文字列の配列）：削除する観察内容
  • 戻り値：成功確認

🔧 Claude Desktop での使用

💾 インストール

pip install mcp-neo4j-memory

⚙️ 設定

次の設定を含めて、サーバーを claude_desktop_config.json に追加します。

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "[email protected]",
      "--db-url",
      "neo4j+s://xxxx.databases.neo4j.io",
      "--username",
      "<your-username>",
      "--password",
      "<your-password>"
    ]
  }
}

または、環境変数を設定できます。

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [ "[email protected]" ],
    "env": {
      "NEO4J_URL": "neo4j+s://xxxx.databases.neo4j.io",
      "NEO4J_USERNAME": "<your-username>",
      "NEO4J_PASSWORD": "<your-password>"
    }
  }
}

名前空間

マルチテナント環境にデプロイする場合は、ツール名にプレフィックスを付けるために --namespace を追加します。

"args": [ "[email protected]", "--namespace", "myapp", "--db-url", "..." ]

ツール名は myapp-read_graph、myapp-create_entities などになります。

NEO4J_NAMESPACE 環境変数も使用できます。

🌐 HTTP トランスポートモード

サーバーは、ウェブベースのデプロイやマイクロサービス向けに HTTP トランスポートをサポートしています。

# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)
mcp-neo4j-memory --transport http

# Custom HTTP configuration
mcp-neo4j-memory --transport http --host 127.0.0.1 --port 8080 --path /mcp/

HTTP 設定用の環境変数：

export NEO4J_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/mcp/
export NEO4J_NAMESPACE=myapp
mcp-neo4j-memory

🔄 トランスポートモード

サーバーは、次の 3 つのトランスポートモードをサポートしています。

• STDIO（デフォルト）：ローカルツールおよび Claude Desktop 用の標準入力／出力
• SSE：ウェブベースのデプロイ向けの Server-Sent Events
• HTTP：最新のウェブデプロイおよびマイクロサービス向けのストリーミング可能な HTTP

🐳 Docker での使用

"mcpServers": {
  "neo4j": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-e", "NEO4J_URL=neo4j+s://xxxx.databases.neo4j.io",
      "-e", "NEO4J_USERNAME=<your-username>",
      "-e", "NEO4J_PASSWORD=<your-password>",
      "mcp/neo4j-memory:0.4.5"
    ]
  }
}

🔒 セキュリティ保護

このサーバーには、HTTP トランスポート使用時に MCP の全機能を維持しながら、一般的なウェブベースの攻撃から保護する、安全なデフォルト設定を備えた包括的なセキュリティ保護機能が含まれています。

🛡️ DNS リバインディング対策

TrustedHost Middleware は、DNS リバインディング攻撃を防ぐために Host ヘッダーを検証します。

デフォルトで安全：

• デフォルトで許可されるホストは localhost と 127.0.0.1 のみです

環境変数：

export NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com"

🌐 CORS 保護

クロスオリジンリソース共有（CORS） 保護により、デフォルトでブラウザーからのリクエストがブロックされます。

環境変数：

export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com,https://app.example.com"

🔧 セキュリティ設定の全体例

開発環境の設定：

mcp-neo4j-memory --transport http \
  --allowed-hosts "localhost,127.0.0.1" \
  --allow-origins "http://localhost:3000"

本番環境の設定：

mcp-neo4j-memory --transport http \
  --allowed-hosts "example.com,www.example.com" \
  --allow-origins "https://example.com,https://app.example.com"

🚨 セキュリティのベストプラクティス

allow_origins の場合：

• 具体的に指定します：["https://example.com", "https://example.com"]
• 本番環境では、認証情報を使用する場合に "*" を使用しないでください
• 本番環境では HTTPS オリジンを使用してください

allowed_hosts の場合：

• 実際のドメインを含めます：["example.com", "www.example.com"]
• localhost を含めるのは開発環境だけにしてください
• リスクを理解している場合を除き、"*" を使用しないでください

🐳 Docker でのデプロイ

Neo4j Memory MCP サーバーは、リモート環境へのデプロイに Docker を使用できます。Docker でデプロイする場合は、ウェブからアクセスできるよう HTTP トランスポートを使用してください。このデプロイを Claude Desktop などのアプリケーションと統合するには、MCP 設定で mcp-remote などのプロキシを使用する必要があります。

📦 ビルド済みイメージの使用

docker build -t mcp-neo4j-memory:latest . を実行してローカルでビルドした後：

# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  mcp/neo4j-memory:latest

# Run with security middleware for production
docker run --rm -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="password" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
  mcp/neo4j-memory:latest

🔧 環境変数

変数	デフォルト	説明
NEO4J_URI	bolt://localhost:7687	Neo4j 接続 URI
NEO4J_USERNAME	neo4j	Neo4j のユーザー名
NEO4J_PASSWORD	password	Neo4j のパスワード
NEO4J_DATABASE	neo4j	Neo4j のデータベース名
NEO4J_TRANSPORT	stdio (local), http (remote)	トランスポートプロトコル（stdio、http、または sse）
NEO4J_MCP_SERVER_HOST	127.0.0.1 (local)	バインドするホスト
NEO4J_MCP_SERVER_PORT	8000	HTTP/SSE トランスポート用のポート
NEO4J_MCP_SERVER_PATH	/mcp/	MCP サーバーにアクセスするためのパス
NEO4J_MCP_SERVER_ALLOW_ORIGINS	(empty - secure by default)	許可する CORS オリジンのカンマ区切りリスト
NEO4J_MCP_SERVER_ALLOWED_HOSTS	localhost,127.0.0.1	許可するホストのカンマ区切りリスト（DNS リバインディング対策）
NEO4J_NAMESPACE	(empty - no prefix)	ツール名の名前空間プレフィックス（例：myapp-read_graph）

🌐 レガシー Web アクセス向け SSE トランスポート

SSE トランスポート（レガシー Web クライアント向け）を使用すると、サーバーは HTTP エンドポイントを公開します。

# Start the server with SSE transport
docker run -d -p 8000:8000 \
  -e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
  -e NEO4J_USERNAME="recommendations" \
  -e NEO4J_PASSWORD="recommendations" \
  -e NEO4J_DATABASE="neo4j" \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-memory-mcp-server \
  mcp-neo4j-memory:latest

# Test the SSE endpoint
curl http://localhost:8000/sse

# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🚀 開発

📦 前提条件

1. uv（Universal Virtualenv）をインストールします：

# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv

2. リポジトリをクローンし、開発環境をセットアップします：

# Clone the repository
git clone https://github.com/yourusername/mcp-neo4j-memory.git
cd mcp-neo4j-memory

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies including dev dependencies
uv pip install -e ".[dev]"

🐳 Docker

Docker コンテナーをビルドして実行します：

# Build the image
docker build -t mcp/neo4j-memory:latest .

# Run the container
docker run -e NEO4J_URL="neo4j+s://xxxx.databases.neo4j.io" \
          -e NEO4J_USERNAME="your-username" \
          -e NEO4J_PASSWORD="your-password" \
          mcp/neo4j-memory:latest

📄 ライセンス

この MCP サーバーは MIT License の下でライセンスされています。MIT License の利用規約に従う限り、このソフトウェアは自由に使用、変更、配布できます。詳細については、プロジェクトリポジトリの LICENSE ファイルを参照してください。