Graphiti MCP Server 🧠

Graphiti MCP Server 🧠

🌟 Neo4j を使用し、Model Context Protocol（MCP）と統合された、AI エージェント向けの高性能なナレッジグラフサーバーです。

🚀 特長

• 🔄 Neo4j による動的なナレッジグラフ管理
• 🤖 OpenAI モデルとのシームレスな統合
• 🔌 MCP（Model Context Protocol）をサポート
• 🐳 Docker 対応のデプロイ
• 🎯 カスタムエンティティ抽出機能
• 🔍 高度なセマンティック検索機能

🛠️ インストール

前提条件

• Docker と Docker Compose
• Python 3.10 以降
• OpenAI API キー
• 最低 4GB の RAM（8GB を推奨）
• 2GB の空きディスク容量

クイックスタート 🚀

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

git clone https://github.com/gifflet/graphiti-mcp-server.git
cd graphiti-mcp-server

2. 環境変数を設定します：

cp .env.sample .env

3. .env を編集して設定を行います：

# Required for LLM operations
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

# Optional: Custom OpenAI endpoint (e.g., for proxies)
# OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j Configuration (defaults work with Docker)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo

4. サービスを起動します：

docker compose up -d

5. インストールを確認します：

# Check if services are running
docker compose ps

# Check logs
docker compose logs graphiti-mcp

代替方法：環境変数

環境変数を直接指定して実行できます：

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

🔧 設定

サービスのポート 🌐

サービス	ポート	用途
Neo4j Browser	7474	グラフを視覚化するための Web インターフェース
Neo4j Bolt	7687	データベース接続
Graphiti MCP	8000	MCP サーバーのエンドポイント

環境変数 🔧

OpenAI の設定

変数	必須	デフォルト	説明
OPENAI_API_KEY	✅	-	OpenAI API キー
OPENAI_BASE_URL	❌	-	カスタム OpenAI API エンドポイント（OpenAI SDK が使用）
MODEL_NAME	❌	gpt-4.1-mini	使用するメインの LLM モデル
SMALL_MODEL_NAME	❌	gpt-4.1-nano	軽量なタスク向けの小型 LLM モデル
LLM_TEMPERATURE	❌	0.0	LLM の温度（0.0～2.0）
EMBEDDER_MODEL_NAME	❌	text-embedding-3-small	埋め込みモデル

Neo4j の設定

変数	必須	デフォルト	説明
NEO4J_URI	❌	bolt://neo4j:7687	Neo4j 接続 URI
NEO4J_USER	❌	neo4j	Neo4j のユーザー名
NEO4J_PASSWORD	❌	demodemo	Neo4j のパスワード

サーバーの設定

変数	必須	デフォルト	説明
MCP_SERVER_HOST	❌	-	MCP サーバーのバインド先ホスト
SEMAPHORE_LIMIT	❌	10	LLM 呼び出しの同時実行数の上限

Azure OpenAI の設定（任意）

Azure OpenAI のデプロイでは、標準の OpenAI 設定の代わりに以下の環境変数を使用します。

変数	必須	デフォルト	説明
AZURE_OPENAI_ENDPOINT	✅*	-	Azure OpenAI のエンドポイント URL
AZURE_OPENAI_API_VERSION	✅*	-	Azure OpenAI の API バージョン
AZURE_OPENAI_DEPLOYMENT_NAME	✅*	-	Azure OpenAI のデプロイ名
AZURE_OPENAI_USE_MANAGED_IDENTITY	❌	false	認証に Azure マネージド ID を使用
AZURE_OPENAI_EMBEDDING_ENDPOINT	❌	-	埋め込み用の別エンドポイント
AZURE_OPENAI_EMBEDDING_API_VERSION	❌	-	埋め込み用の API バージョン
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME	❌	-	埋め込み用のデプロイ名
AZURE_OPENAI_EMBEDDING_API_KEY	❌	-	埋め込み用の別の API キー

* Azure OpenAI の使用時に必須です

注：

• OPENAI_BASE_URL は OpenAI Python SDK が直接使用します。プロキシ構成やカスタムエンドポイントで役立ちます
• SEMAPHORE_LIMIT は LLM API 呼び出しの同時実行数を制御します。レート制限に達した場合は値を下げ、スループットを高める場合は値を上げてください
• Azure の設定は標準の OpenAI 設定に代わるものです。両方の設定を混在させないでください

Neo4j の設定 🗄️

Neo4j のデフォルト設定：

• ユーザー名：neo4j
• パスワード：demodemo
• URI：bolt://neo4j:7687（Docker ネットワーク内）
• 開発向けに最適化されたメモリ設定

Docker 環境変数 🐳

環境変数を直接指定して実行できます：

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Azure OpenAI の場合：

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
AZURE_OPENAI_API_VERSION=2024-02-01 \
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment \
OPENAI_API_KEY=your_key \
docker compose up

🔌 インテグレーション

Cursor IDE とのインテグレーション 🖥️

1. Cursor MCP の設定を行います：

{
  "mcpServers": {
    "Graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

2. Docker ベースのセットアップの場合：

{
  "mcpServers": {
    "Graphiti": {
      "url": "http://localhost:8000/sse"
    }
  }
}

3. Cursor のユーザールールに Graphiti のルールを追加します（graphiti_cursor_rules.mdc を参照）
4. Cursor でエージェントのセッションを開始します

その他の MCP クライアント

このサーバーは標準の MCP トランスポートをサポートしています：

• SSE（Server-Sent Events）： http://localhost:8000/sse
• WebSocket： ws://localhost:8000/ws
• Stdio： プロセス間の直接通信

💻 開発

ローカル開発環境のセットアップ

1. 依存関係をインストールします：

# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or using pip
pip install -r requirements.txt

2. Neo4j をローカルで起動します：

docker run -d \
  --name neo4j-dev \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/demodemo \
  neo4j:5.26.0

3. サーバーを実行します：

# Set environment variables
export OPENAI_API_KEY=your_key
export NEO4J_URI=bolt://localhost:7687

# Run with stdio transport
uv run graphiti_mcp_server.py

# Or with SSE transport
uv run graphiti_mcp_server.py --transport sse --use-custom-entities

テスト

# Run basic connectivity test
curl http://localhost:8000/health

# Test MCP endpoint
curl http://localhost:8000/sse

🔍 トラブルシューティング

よくある問題

🐳 Docker の問題

# Clean up and restart
docker compose down -v
docker compose up --build

# Check disk space
docker system df

ログとデバッグ

# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f graphiti-mcp
docker compose logs -f neo4j

# Enable debug logging
docker compose up -e LOG_LEVEL=DEBUG

パフォーマンスの問題

• メモリ： docker-compose.yml で Neo4j のヒープサイズを増やします
• ストレージ： Neo4j のデータボリュームの使用状況を監視します
• ネットワーク： ポート 7474、7687、8000 がファイアウォールでブロックされていないか確認します

🏗️ アーキテクチャ

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  Graphiti MCP    │    │     Neo4j       │
│   (Cursor)      │◄──►│     Server       │◄──►│   Database      │
│                 │    │   (Port 8000)    │    │  (Port 7687)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   OpenAI API     │
                       │   (LLM Client)   │
                       └──────────────────┘

コンポーネント

• Neo4j Database： グラフの保存とクエリ
• Graphiti MCP Server： API 層と LLM 操作
• OpenAI Integration： エンティティ抽出とセマンティック処理
• MCP Protocol： AI エージェント間の標準化された通信

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

📝 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• 優れたグラフデータベースを提供する Neo4j チーム
• 強力な LLM モデルを提供する OpenAI
• プロトコル仕様を提供する MCP community
• ナレッジグラフのフレームワークを提供する Graphiti Core

---

お困りですか？ イシューを作成するか、上記のトラブルシューティングガイドをご確認ください。