mcp-neo4j-cypher

🔍⁉️ Neo4j MCP サーバー

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

🌟 概要

Neo4j を通じてデータベースとのやり取りを行い、グラフの探索機能を提供する Model Context Protocol（MCP）サーバーの実装です。このサーバーを使うと、Cypher グラフクエリを実行し、複雑なドメインデータを分析して、アプリケーションの分析ツールでさらに強化できるビジネスインサイトを自動生成できます。

この MCP サーバーは、以下に詳述するような Text2Cypher ワークフローを実現します。

• 青色のステップはエージェントが処理します
• 紫色のステップは Cypher または別の MCP サーバーが処理します
• 緑色のステップはユーザーが処理します

ユーザーの質問をプロセスに入力すると、エージェントが生成した回答が出力されます。

📋 前提条件

• Neo4j Database：実行中の Neo4j インスタンス（Aura または Self-Managed）
• APOC Plugin：Neo4j インスタンスに APOC プラグインをインストールして有効化する必要があります。get_neo4j_schema ツールを正しく動作させるために必要です。

🧩 コンポーネント

🛠️ ツール

サーバーでは、次の主要なツールを利用できます。

📊 クエリツール

• read_neo4j_cypher

  • データベースからデータを読み取る Cypher 読み取りクエリを実行します
  • 入力：
    • query（string）：実行する Cypher クエリ
    • params（dictionary、任意）：Cypher クエリに渡すパラメーター
  • 戻り値：オブジェクトの配列を JSON にシリアライズしたクエリ結果
  • タイムアウト：会話の流れを妨げる長時間実行クエリを防ぐため、読み取りクエリには設定可能なタイムアウト（デフォルト：30 秒）が適用されます

• write_neo4j_cypher

  • Cypher 更新クエリを実行します
  • 入力：
    • query（string）：実行する Cypher 更新クエリ
    • params（dictionary、任意）：Cypher クエリに渡すパラメーター
  • 戻り値：{ nodes_updated: number, relationships_created: number, ... } 形式の結果概要カウンターを JSON にシリアライズしたもの
  • 利用可否：CLI フラグとして --read-only を指定するか、環境変数 NEO4J_READ_ONLY=true を設定すると無効になります

🕸️ スキーマツール

• get_neo4j_schema
  • グラフデータベース内のすべてのノードタイプと、その名前および型を含む属性、ほかのノードタイプとのリレーションシップの一覧を取得します
  • 要件：APOC プラグインをインストールして有効化する必要があります。
  • 入力：
    • sample_param（integer、任意）：スキーマ分析のためにサンプリングするノード数。指定すると、サーバーのデフォルト値を上書きします。
  • 戻り値：2 つの辞書（属性用とリレーションシップ用）を含むノードラベルの一覧を JSON にシリアライズしたもの
  • パフォーマンス：デフォルトではサンプリングを使用します（ラベルごとに 1000 ノード）。大規模なデータベースで分析を高速化するには、数を減らしてください。サンプリングを停止するには、-1 を設定します。

🏷️ 名前空間

サーバーは名前空間に対応しており、複数の Neo4j MCP サーバーを同時に使用できます。名前空間を指定すると、すべてのツール名の先頭に名前空間とハイフンが付与されます（例：mydb-read_neo4j_cypher）。

これは、同じセッションから複数の Neo4j データベースまたはインスタンスに接続する必要がある場合に便利です。

⚙️ クエリ設定

サーバーには、クエリのパフォーマンスを最適化し、レスポンスのサイズを管理するための設定オプションがあります。

⏱️ クエリのタイムアウト

長時間実行クエリによって会話の流れが妨げられないよう、読み取りクエリのタイムアウトを設定します。

コマンドライン：

mcp-neo4j-cypher --read-timeout 60  # 60 seconds

環境変数：

export NEO4J_READ_TIMEOUT=60

Docker：

docker run -e NEO4J_READ_TIMEOUT=60 mcp-neo4j-cypher:latest

デフォルト：30 秒。このタイムアウトを超えた読み取りクエリは、AI モデルとの応答性の高いやり取りを維持するため、自動的にキャンセルされます。

📏 トークン制限

AI モデルに過剰な負荷をかけないよう、クエリ応答の最大サイズを制御します。

コマンドライン：

mcp-neo4j-cypher --token-limit 4000

環境変数：

export NEO4J_RESPONSE_TOKEN_LIMIT=4000

Docker：

docker run -e NEO4J_RESPONSE_TOKEN_LIMIT=4000 mcp-neo4j-cypher:latest

応答がトークン制限を超えた場合、tiktoken を使用して指定された制限内に収まるよう自動的に切り詰められます。これにより、次のことが保証されます。

• 一貫したパフォーマンス：応答がモデルのコンテキスト制限内に収まります
• コスト管理：AI とのやり取りで過剰なトークンが使用されるのを防ぎます
• 信頼性：大規模なデータセットによって会話の流れが中断されることはありません

注：トークン制限は read_neo4j_cypher の応答にのみ適用されます。スキーマクエリと書き込み操作は要約情報を返すため、影響を受けません。

🔍 スキーマのサンプリング

get_neo4j_schema ツールの sample パラメーターを使用して、スキーマ検査のパフォーマンスと範囲を制御します。

コマンドライン：

mcp-neo4j-cypher --sample 1000  # Sample 1000 nodes per label

環境変数：

export NEO4J_SCHEMA_SAMPLE_SIZE=1000

Docker：

docker run -e NEO4J_SCHEMA_SAMPLE_SIZE=1000 mcp-neo4j-cypher:latest

sample パラメーターは、データベーススキーマの生成時に検査するノード数を制御します。

• デフォルト：スキーマ分析では、ラベルごとに 1000 個のノードがサンプリングされます
• パフォーマンス：値を小さく（100、500）すると、大規模なデータベースでのスキーマ検査が速くなります
• 精度：値を大きく（5000、10000）すると、より包括的にスキーマを把握できます
• 全件スキャン：-1 に設定すると、すべてのノードを検査します（大規模なデータベースでは非常に時間がかかる場合があります）
• 呼び出しごとの上書き：get_neo4j_schema ツールの sample_param パラメーターを使用して、サーバーのデフォルト値を上書きできます

サンプリングの仕組み（APOC の apoc.meta.schema を使用）：

• 各ノードラベルについて、スキップ数が次の式で計算されます：totalNodesForLabel / sample ± 10%
• スキップ数に基づき、N 個ごとのノードが検査されます
• サンプル数が多いほど、検査されるノードが増えます
• ランダムサンプリングのため、実行ごとに結果が異なる場合があります

使用例：

# Fast schema inspection for large databases
export NEO4J_SCHEMA_SAMPLE_SIZE=100

# Balanced performance and accuracy (default)
export NEO4J_SCHEMA_SAMPLE_SIZE=1000

# Comprehensive schema analysis
export NEO4J_SCHEMA_SAMPLE_SIZE=5000

# Full database scan (use with caution on large databases)
export NEO4J_SCHEMA_SAMPLE_SIZE=-1

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

• 大規模なデータベース：タイムアウトを防ぐため、サンプル値を小さく（100-500）します
• 開発：スキーマを詳しく把握するには、サンプル値を大きく（1000-5000）します
• 本番環境：用途に応じて、パフォーマンスとスキーマの網羅性のバランスを取ります

🏗️ ローカル開発とデプロイ

🐳 ローカル Docker 開発

テストまたはリモートデプロイ用に、ローカルでビルドして実行します。

# Build the Docker image with a custom name from your local version of the server
docker build -t mcp-neo4j-cypher:latest .

# Run locally (uses http transport by default for Docker)
docker run -p 8000:8000 \
  -e NEO4J_URI="bolt://host.docker.internal:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="your-password" \
  mcp-neo4j-cypher:latest

# Access the server at http://localhost:8000/mcp/

🚀 トランスポートモード

サーバーは、デプロイ環境に応じて異なるトランスポートプロトコルをサポートします。

• STDIO（ローカル開発用）：Claude Desktop およびローカルツール向けの標準入出力
• HTTP（リモートデプロイ用）：Web デプロイおよびマイクロサービス向けの RESTful HTTP
• SSE：従来の Web ベースのデプロイ向けの Server-Sent Events

用途に応じてトランスポートを選択してください。

• ローカル開発／Claude Desktop：stdio を使用します
• リモートデプロイ：http を使用します
• 従来の Web クライアント：sse を使用します

🔒 セキュリティ保護

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

🛡️ DNS リバインディング保護

TrustedHost ミドルウェアは Host ヘッダーを検証し、DNS リバインディング攻撃を防ぎます。

デフォルトで安全：

• デフォルトでは localhost と 127.0.0.1 のホストのみが許可されます
• 悪意のある Web サイトがブラウザーをだましてローカルサーバーにアクセスさせることはできません

環境変数：

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

🌐 CORS 保護

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

環境変数：

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

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

開発環境の設定：

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

本番環境の設定：

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

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

allow_origins について：

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

allowed_hosts について：

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

🔧 Claude Desktop での使用方法

DXT の使用

リリースページから最新の .dxt ファイルをダウンロードし、お使いの MCP クライアントにインストールします。

💾 リリース済みパッケージ

PyPi https://pypi.org/project/mcp-neo4j-cypher/ にあります。

環境変数を使ってデータベース接続を設定し、claude_desktop_config.json にサーバーを追加します。トランスポート方式、名前空間、その他の設定変数は、CLI 引数または環境変数で指定することもできます。

{
  "mcpServers": {
    "neo4j-database": {
      "command": "uvx",
      "args": [ "[email protected]", "--transport", "stdio"  ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<your-password>",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

🌐 HTTP トランスポートの設定

セキュリティミドルウェアを使用したカスタム HTTP 設定については、次のとおりです。

# Complete HTTP configuration with security
mcp-neo4j-cypher --transport http \
  --server-host 127.0.0.1 \
  --server-port 8080 \
  --server-path /mcp/ \
  --allowed-hosts "localhost,127.0.0.1,example.com" \
  --allow-origins "https://yourapp.com"

# Using environment variables
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_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1,example.com"
export NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://yourapp.com"
mcp-neo4j-cypher

複数データベースの例

名前空間を使って複数の Neo4j データベースに接続する例を示します。

{
  "mcpServers": {
    "movies-neo4j": {
      "command": "uvx",
      "args": ["[email protected]", "--namespace", "movies"],
      "env": {
        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
        "NEO4J_USERNAME": "recommendations",
        "NEO4J_PASSWORD": "recommendations",
        "NEO4J_DATABASE": "recommendations"
      }
    },
    "local-neo4j": {
      "command": "uvx",
      "args": ["[email protected]"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_NAMESPACE": "local"
      }
    }
  }
}

この設定では：

• movies データベースのツールには movies- というプレフィックスが付きます（例：movies-read_neo4j_cypher）
• local データベースのツールには local- というプレフィックスが付きます（例：local-get_neo4j_schema）

--db-url、--username、--password、--read-timeout などのコマンドライン引数を使う構文も引き続きサポートされていますが、環境変数の使用を推奨します：

"mcpServers": {
  "neo4j": {
    "command": "uvx",
    "args": [
      "[email protected]",
      "--db-url",
      "bolt://localhost",
      "--username",
      "neo4j",
      "--password",
      "<your-password>",
      "--namespace",
      "mydb",
      "--transport",
      "sse",
      "--server-host",
      "127.0.0.1",
      "--server-port",
      "8000"
      "--server-path",
      "/mcp/"
    ]
  }
}

🐳 Docker での使用

ここでは、Claude Desktop で使用するため、Docker Hub でホストされている Cypher MCP サーバーのイメージを stdio トランスポートで使用します。

設定の詳細：

• -i：インタラクティブモード。stdio トランスポート通信のために STDIN を開いたままにします
• --rm：終了時にコンテナを自動的に削除します（クリーンアップ）
• -p 8000:8000：ポートマッピング。ホストのポート 8000 をコンテナのポート 8000 に割り当てます
• NEO4J_TRANSPORT=stdio：Claude Desktop との互換性のために stdio トランスポートを使用します
• NEO4J_NAMESPACE=neo4j：ツールに「neo4j-」というプレフィックスを付けます（例：neo4j-read_neo4j_cypher）
• NEO4J_URI=bolt://host.docker.internal:7687：Docker コンテナからホストマシン上で実行中の Neo4j に接続できるようにします

{
  "mcpServers": {
    "neo4j": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", 
        "8000:8000",
        "-e", "NEO4J_URI=bolt://host.docker.internal:7687",
        "-e", "NEO4J_USERNAME=neo4j",
        "-e", "NEO4J_PASSWORD=password",
        "-e", "NEO4J_NAMESPACE=neo4j",
        "-e", "NEO4J_TRANSPORT=stdio",
        "mcp/neo4j-cypher:latest"
      ]
    }
  }
}

🐳 Docker によるデプロイ

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

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

docker build -t mcp-neo4j-cypher: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-cypher: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-cypher:latest

🔧 環境変数

🌐 従来の 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="recommendations" \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-mcp-server \
  mcp-neo4j-cypher:latest

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

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

🐳 Docker Compose

より複雑なデプロイには、Docker Compose を使用できます。

version: '3.8'

services:
  # Deploy Neo4j Database (optional)
  neo4j:
    image: neo4j:5.26.1 # or another version
    environment:
      - NEO4J_AUTH=neo4j/password
      - NEO4J_PLUGINS=["apoc"]
    ports:
      - '7474:7474' # HTTP
      - '7687:7687' # Bolt
    volumes:
      - neo4j_data:/data

  # Deploy Cypher MCP Server
  mcp-neo4j-cypher-server:
    image: mcp/neo4j-cypher:latest
    ports:
      - '8000:8000'
    environment:
      - NEO4J_URI=bolt://host.docker.internal:7687
      - NEO4J_USERNAME=neo4j
      - NEO4J_PASSWORD=password
      - NEO4J_DATABASE=neo4j
      - NEO4J_TRANSPORT=http
      - NEO4J_MCP_SERVER_HOST=0.0.0.0 # must be 0.0.0.0 for sse  or http transport in Docker
      - NEO4J_MCP_SERVER_PORT=8000
      - NEO4J_MCP_SERVER_PATH=/mcp/
      - NEO4J_NAMESPACE=local
    depends_on:
      - neo4j

volumes:
  neo4j_data:

次のコマンドで実行します：docker-compose up -d

🔗 Docker を使用した Claude Desktop との統合

HTTP トランスポートを使用する Docker 化されたサーバーを Claude Desktop と統合する場合：

{
  "mcpServers": {
    "neo4j-docker": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://localhost:8000/mcp/"]
    }
  }
}

注：まず Docker コンテナを HTTP トランスポートで起動してください。その後、Claude Desktop は HTTP エンドポイントと mcp-remote などのプロキシサーバーを介して接続できます。

🚀 開発

📦 前提条件

1. uv をインストールします。

# 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/neo4j-contrib/mcp-neo4j.git
cd mcp-neo4j-cypher

# 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]"

3. 統合テストを実行します。

./tests.sh

🔧 開発設定

ローカルソースを使用して Claude Desktop で開発する場合：

{
  "mcpServers": {
    "neo4j-dev": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-neo4j-cypher", "run", "mcp-neo4j-cypher", "--transport", "stdio", "--namespace", "dev"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<your-password>",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

/path/to/mcp-neo4j-cypher を実際のプロジェクトディレクトリのパスに置き換えてください。

📄 ライセンス

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