Graphiti MCP サーバー

Graphitiは、時間的変化を考慮したナレッジグラフの構築とクエリのためのフレームワークであり、動的な環境で動作するAIエージェント向けに特化されています。従来の検索拡張型生成（RAG）手法とは異なり、Graphitiはユーザーインタラクション、構造化および非構造化エンタープライズデータ、そして外部情報を、一貫性がありクエリ可能なグラフに継続的に統合します。このフレームワークは、グラフ全体の再計算を必要とせずに、増分データ更新、効率的な検索、そして正確な履歴クエリをサポートしているため、インタラクティブでコンテキストアウェアなAIアプリケーションの開発に最適です。

これはGraphiti向けの実験的なモデルコンテキストプロトコル（MCP）サーバー実装です。MCPサーバーはGraphitiの主要機能をMCPプロトコルを通じて公開し、AIアシスタントがGraphitiのナレッジグラフ機能を利用できるようにします。

特徴

Graphiti MCP サーバーは、Graphiti の次の主要な高レベル機能を公開します。

• エピソード管理: エピソード (テキスト、メッセージ、または JSON データ) の追加、取得、削除

• エンティティ管理: ナレッジグラフ内のエンティティノードと関係を検索および管理します。

• 検索機能: セマンティック検索とハイブリッド検索を使用してファクト（エッジ）とノードサマリーを検索します

• グループ管理: group_id フィルタリングを使用して関連データのグループを整理および管理します。

• グラフのメンテナンス: グラフをクリアしてインデックスを再構築します

Related MCP server: Gitingest MCP Server

Claude Desktop、Cursor、その他のクライアントのクイックスタート

1. Graphiti GitHubリポジトリをクローンする

git clone https://github.com/getzep/graphiti.git

または

gh repo clone getzep/graphiti

このディレクトリへの完全なパスをメモしてください。

cd graphiti && pwd

2. Graphiti の前提条件をインストールします。

3. Claude、Cursor、またはその他のMCPクライアントをstdioトランスポートでGraphitiを使用するように設定します。MCP設定ファイルの場所については、クライアントのドキュメントを参照してください。

インストール

前提条件

1. Python 3.10 以降がインストールされていることを確認してください。

2. 実行中の Neo4j データベース (バージョン 5.26 以降が必要)

3. LLM操作用のOpenAI APIキー

設定

1. リポジトリをクローンし、mcp_serverディレクトリに移動します。

2. uvを使用して仮想環境を作成し、依存関係をインストールします。

# Install uv if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install dependencies in one step
uv sync

構成

サーバーは次の環境変数を使用します。

• NEO4J_URI : Neo4j データベースの URI (デフォルト: bolt://localhost:7687 )

• NEO4J_USER : Neo4j ユーザー名 (デフォルト: neo4j )

• NEO4J_PASSWORD : Neo4j パスワード (デフォルト: demodemo )

• OPENAI_API_KEY : OpenAI API キー (LLM 操作に必要)

• OPENAI_BASE_URL : OpenAI API のオプションのベース URL

• MODEL_NAME : LLM 操作に使用する OpenAI モデル名。

• SMALL_MODEL_NAME : 小規模な LLM 操作に使用する OpenAI モデル名。

• LLM_TEMPERATURE : LLM 応答の温度 (0.0-2.0)。

• AZURE_OPENAI_ENDPOINT : オプションの Azure OpenAI エンドポイント URL

• AZURE_OPENAI_DEPLOYMENT_NAME : オプションの Azure OpenAI デプロイメント名

• AZURE_OPENAI_API_VERSION : オプションの Azure OpenAI API バージョン

• AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME : オプションの Azure OpenAI 埋め込みデプロイメント名

• AZURE_OPENAI_EMBEDDING_API_VERSION : オプションの Azure OpenAI API バージョン

• AZURE_OPENAI_USE_MANAGED_IDENTITY : 認証に Azure マネージド ID を使用する (オプション)

これらの変数は、プロジェクト ディレクトリ内の.envファイルで設定できます。

サーバーの実行

uvを使用して Graphiti MCP サーバーを直接実行するには:

uv run graphiti_mcp_server.py

オプション付き:

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

使用可能な引数:

• --model : MODEL_NAME環境変数を上書きします。

• --small-model : SMALL_MODEL_NAME環境変数を上書きします。

• --temperature : LLM_TEMPERATURE環境変数を上書きします。

• --transport : 転送方法を選択します (sse または stdio、デフォルト: sse)

• --group-id : グラフの名前空間を設定します（オプション）。指定しない場合は、デフォルトで「default」になります。

• --destroy-graph : 設定されている場合、起動時にすべての Graphiti グラフを破棄します。

• --use-custom-entities : 定義済みのENTITY_TYPESを使用してエンティティ抽出を有効にする

Docker デプロイメント

Graphiti MCPサーバーはDockerを使用してデプロイできます。Dockerfileはパッケージ管理にuvを使用し、依存関係のインストールの一貫性を確保します。

環境設定

Docker Compose のセットアップを実行する前に、環境変数を設定する必要があります。2 つのオプションがあります。

1. .env ファイルの使用(推奨):

   • 提供されている.env.exampleファイルをコピーして.envファイルを作成します。

     cp .env.example .env

   • .envファイルを編集して、OpenAI API キーやその他の構成オプションを設定します。

     # Required for LLM operations
     OPENAI_API_KEY=your_openai_api_key_here
     MODEL_NAME=gpt-4.1-mini
     # Optional: OPENAI_BASE_URL only needed for non-standard OpenAI endpoints
     # OPENAI_BASE_URL=https://api.openai.com/v1

   • Docker Compose セットアップは、このファイルが存在する場合はそれを使用するように構成されています (オプション)

2. 環境変数を直接使用する:

   • Docker Compose コマンドを実行するときに環境変数を設定することもできます。

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

Neo4j の設定

Docker Compose セットアップには、次のデフォルト構成の Neo4j コンテナーが含まれています。

• ユーザー名: neo4j

• パスワード: demodemo

• URI: bolt://neo4j:7687 (Docker ネットワーク内から)

• 開発用途に最適化されたメモリ設定

Docker Composeで実行する

Docker Compose を使用してサービスを開始します。

docker compose up

または、古いバージョンの Docker Compose を使用している場合:

docker-compose up

これにより、Neo4jデータベースとGraphiti MCPサーバーの両方が起動します。Dockerのセットアップは以下のとおりです。

• パッケージ管理とサーバーの実行にはuvを使用します

• pyproject.tomlファイルから依存関係をインストールします

• 環境変数を使用してNeo4jコンテナに接続する

• HTTPベースのSSEトランスポート用にポート8000でサーバーを公開します

• MCP サーバーを起動する前に、Neo4j が完全に機能していることを確認するためのヘルスチェックが含まれています。

MCPクライアントとの統合

構成

Graphiti MCP サーバーを MCP 互換クライアントで使用するには、サーバーに接続するように構成します。

[!重要] Pythonパッケージマネージャーuvがインストールされている必要があります。uv uvインストール手順を参照してください。

uvバイナリと Graphiti プロジェクト フォルダーへの完全なパスが設定されていることを確認してください。

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>>/dev/zep/graphiti/mcp_server",
        "--project",
        ".",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

SSE トランスポート (HTTP ベース) の場合、次の構成を使用できます。

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

利用可能なツール

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

• add_episode : ナレッジグラフにエピソードを追加します（テキスト、JSON、メッセージ形式をサポート）

• search_nodes : 関連するノードサマリーをナレッジグラフで検索する

• search_facts : ナレッジグラフで関連する事実（エンティティ間のエッジ）を検索する

• delete_entity_edge : ナレッジグラフからエンティティエッジを削除する

• delete_episode : ナレッジグラフからエピソードを削除する

• get_entity_edge : UUIDでエンティティエッジを取得する

• get_episodes : 特定のグループの最新のエピソードを取得する

• clear_graph : ナレッジグラフからすべてのデータをクリアし、インデックスを再構築します。

• get_status : Graphiti MCPサーバーとNeo4j接続のステータスを取得します。

JSONデータの操作

Graphiti MCPサーバーは、 add_episodeツールでsource="json"を指定した構造化JSONデータを処理できます。これにより、構造化データからエンティティとリレーションシップを自動的に抽出できます。

add_episode(
name="Customer Profile",
episode_body="{\"company\": {\"name\": \"Acme Technologies\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\"}, {\"id\": \"P002\", \"name\": \"DataMiner\"}]}",
source="json",
source_description="CRM data"
)

カーソルIDEとの統合

Graphiti MCP Server を Cursor IDE と統合するには、次の手順に従います。

1. SSE トランスポートを使用して Graphiti MCP サーバーを実行します。

python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

ヒント: 名前空間グラフデータにgroup_idを指定してください。group_id を指定しない場合、サーバーはgroup_idとして「default」を使用します。

または

docker compose up

2. Cursor を Graphiti MCP サーバーに接続するように設定します。

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

3. CursorのユーザールールにGraphitiルールを追加します。詳細はcursor_rules.mdを参照してください。

4. Cursor でエージェント セッションを開始します。

この統合により、Cursor の AI アシスタントは Graphiti のナレッジ グラフ機能を通じて永続的なメモリを維持できるようになります。

Claude Desktop（Docker MCP Server）との統合

Graphiti MCP ServerコンテナはSSE MCPトランスポートを使用します。Claude DesktopはSSEをネイティブにサポートしていないため、 mcp-remoteなどのゲートウェイを使用する必要があります。

1. SSE トランスポートを使用して Graphiti MCP サーバーを実行します。

   docker compose up

2. (オプション) mcp-remoteグローバルにインストールする: mcp-remoteグローバルにインストールしたい場合、またはnpxによるパッケージの取得で問題が発生する場合は、グローバルにインストールできます。それ以外の場合は、次の手順で使用npxが自動的に処理します。

   npm install -g mcp-remote

3. Claude Desktop を構成する: Claude Desktop 構成ファイル (通常はclaude_desktop_config.json ) を開き、次のようにmcpServersセクションを追加または変更します。

   {
     "mcpServers": {
       "graphiti-memory": {
         // You can choose a different name if you prefer
         "command": "npx", // Or the full path to mcp-remote if npx is not in your PATH
         "args": [
           "mcp-remote",
           "http://localhost:8000/sse" // Ensure this matches your Graphiti server's SSE endpoint
         ]
       }
     }
   }

   すでにmcpServersエントリがある場合は、その中に新しいキーとしてgraphiti-memory (または選択した名前) を追加します。

4. 変更を有効にするには、 Claude Desktop を再起動してください。

要件

• Python 3.10以上

• Neo4j データベース (バージョン 5.26 以降が必要)

• OpenAI API キー（LLM 操作および埋め込み用）

• MCP互換クライアント

ライセンス

このプロジェクトは、親の Graphiti プロジェクトと同じライセンスの下でライセンスされます。