Neo4j MCP Server for Cursor

Cursor 向け Neo4j MCP サーバー

Cursor IDE から Neo4j データベースを直接シームレスに操作できる、Cursor 用 MCP（Model Context Protocol）サーバーです。

機能

• Neo4j データベースに接続します
• Cypher クエリを実行し、結果を取得します
• Neo4j 固有のデータ型を標準の JavaScript オブジェクトに変換します
• 公式 MCP SDK と stdio トランスポートを使用し、Cursor とシームレスに連携します
• 安全な認証情報管理のため、環境変数をサポートします
• 詳細なデータベース情報とメトリクスを取得します
• 接続状態と診断情報を監視します

前提条件

• Bun（v1.0.0 以上）
• Neo4j データベース（ローカルまたはリモート）

Docker Compose で Neo4j を実行する

このプロジェクトには、Neo4j をコンテナで簡単に実行するための Docker Compose 設定が含まれています。

1. Docker と Docker Compose がインストールされていることを確認します。

2. Docker Compose を使用して Neo4j を起動します。

   docker-compose up -d
   

3. Neo4j Browser にアクセスします：http://localhost:7474

   • デフォルトのユーザー名：neo4j
   • デフォルトのパスワード：your_password（docker-compose.yml で指定されています）

4. Neo4j を停止するには：

   docker-compose down
   

5. Neo4j を停止してすべてのデータを削除するには：

   docker-compose down -v
   

Note：docker-compose.yml のデフォルトパスワードは your_password に設定されています。本番環境で使用する場合は、安全なパスワードに変更し、それに合わせて .env ファイルを更新してください。

インストール

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

   git clone https://github.com/yourusername/neo4j-mcp.git
   cd neo4j-mcp
   

2. 依存関係をインストールします。

   bun install
   

3. 環境変数を設定します。 ルートディレクトリに .env ファイルを作成し、Neo4j の認証情報を記述します。

   NEO4J_URI=neo4j://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your_password
   NEO4J_DATABASE=neo4j
   NODE_ENV=development
   

使い方

サーバーの起動

このサーバーは Cursor との通信に stdio トランスポートを使用するため、Cursor 自身が起動する必要があります。ただし、手動でテストすることもできます。

# Run directly
bun run index.ts

# Run with logging using the provided script
./run-mcp-server.sh

利用可能なツール

MCP サーバーは次のツールを公開します。

1. 明示的な認証情報で Neo4j に接続する

指定された認証情報を使用して Neo4j データベースに接続します。

パラメーター：

• uri：Neo4j データベースの URI（例：neo4j://localhost:7687）
• username：Neo4j データベースのユーザー名
• password：Neo4j データベースのパスワード
• database：（任意）Neo4j データベース名

2. 環境変数で Neo4j に接続する

環境変数の認証情報を使用して Neo4j データベースに接続します。

パラメーターは不要です。

3. Cypher クエリを実行する

接続中の Neo4j データベースに対して Cypher クエリを実行します。

パラメーター：

• query：実行する Cypher クエリ
• params：（任意）クエリパラメーター

4. データベース情報を取得する

接続中の Neo4j データベースに関する詳細情報を取得します。次の情報が含まれます。

• Neo4j のバージョンとエディション
• データベース名
• ノードとリレーションシップの数
• 利用可能なラベル
• リレーションシップの種類

パラメーターは不要です。

5. 接続状態を取得する

現在の接続状態を取得します。次の情報が含まれます。

• 接続状態（接続済み／切断済み）
• 接続の詳細（URI、データベース）
• 接続時刻
• 最後に発生したエラー（ある場合）

パラメーターは不要です。

6. Neo4j から切断する

Neo4j データベースから切断します。

パラメーターは不要です。

環境変数

次の環境変数を .env ファイルに設定できます。

変数	説明	デフォルト
NEO4J_URI	Neo4j データベースの URI	neo4j://localhost:7687
NEO4J_USERNAME	Neo4j データベースのユーザー名	neo4j
NEO4J_PASSWORD	Neo4j データベースのパスワード	（空）
NEO4J_DATABASE	Neo4j データベース名	（デフォルトのデータベース）
NODE_ENV	環境（開発／本番）	development

Cursor との連携

この MCP サーバーは、Cursor の MCP 連携で使用することを想定しています。Cursor は、このサーバーが提供するツールを自動的に検出して使用します。

開発

プロジェクト構成

• index.ts - MCP サーバーを起動するエントリーポイント
• src/mcpNeo4jServer.ts - MCP SDK を使用した MCP サーバーの実装
• src/services/neo4jService.ts - データベース操作を行う Neo4j サービス
• src/types/index.ts - TypeScript の型定義
• src/utils/errorHandler.ts - エラー処理用のユーティリティ関数

本番環境向けのビルド

本番環境向けにサーバーをビルドするには、次のようにします。

# Build the server
bun build index.ts --outdir ./dist

# Make the output file executable
chmod +x ./dist/index.js

ビルドプロセスでは、すべての依存関係が 1 つの JavaScript ファイルにバンドルされるため、依存関係をインストールせずにサーバーを簡単に配布して実行できます。

サーバーの実行

付属のシェルスクリプトを使用してサーバーを実行できます。

./run-mcp-server.sh

このスクリプトは次の処理を行います。

• 作業ディレクトリをスクリプトの場所に設定します
• 存在しない場合は logs ディレクトリを作成します
• Bun を使用してサーバーを実行し、出力を logs/mcp-server.log に記録します

注：このスクリプトを実行するには、Bun がインストールされ、PATH から利用できる必要があります。

ライセンス

MIT