# getzep
## 基本信息
- Slug: `getzep-graphiti`
- Source: modelscope
- Publisher: @getzep/graphiti
- Categories: knowledge-and-memory / rag-systems / databases
- Hosted: No
- License: Apache License 2.0
- Source URL: https://www.modelscope.cn/mcp/servers/@getzep/graphiti
## 简介
暂无描述。
## MCP Server 详情

# Graphiti MCP 服务器

Graphiti 是一个用于构建和查询具有时间感知的知识图谱的框架，特别适用于在动态环境中运行的 AI 代理。与传统的检索增强生成（RAG）方法不同，Graphiti 持续整合用户交互、结构化和非结构化企业数据以及外部信息，形成一个连贯且可查询的图谱。该框架支持增量数据更新、高效检索和精确的历史查询，而无需完全重新计算图谱，使其适合开发交互式、上下文感知的 AI 应用程序。

这是一个实验性的 Model Context Protocol (MCP) 服务器实现，用于 Graphiti。MCP 服务器通过 MCP 协议暴露了 Graphiti 的关键功能，使 AI 助手能够与 Graphiti 的知识图谱能力进行交互。

## 特性

Graphiti MCP 服务器暴露了以下 Graphiti 的关键高级功能：

- **情节管理**：添加、检索和删除情节（文本、消息或 JSON 数据）
- **实体管理**：搜索和管理知识图谱中的实体节点和关系
- **搜索能力**：使用语义和混合搜索查找事实（边）和节点摘要
- **组管理**：通过 `group_id` 过滤来组织和管理相关数据组
- **图维护**：清除图谱并重建索引

## Claude Desktop、Cursor 和其他客户端的快速启动

1. 克隆 Graphiti GitHub 仓库

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


或者

bash
gh repo clone getzep/graphiti


记下此目录的完整路径。

bash
cd graphiti && pwd


2. 安装 [Graphiti 前提条件](#prerequisites)。

3. 配置 Claude、Cursor 或其他 MCP 客户端以使用 [带有 `stdio` 传输的 Graphiti](#integrating-with-mcp-clients)。请参阅客户端文档以了解其 MCP 配置文件的位置。

## 安装

### 前提条件

1. 确保已安装 Python 3.10 或更高版本。
2. 正在运行的 Neo4j 数据库（需要 5.26 或更高版本）
3. 用于 LLM 操作的 OpenAI API 密钥

### 设置

1. 克隆仓库并导航到 mcp_server 目录
2. 使用 `uv` 创建虚拟环境并安装依赖项：

bash
# 如果尚未安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 一步创建虚拟环境并安装依赖项
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 托管标识进行身份验证

您可以在项目目录中通过 `.env` 文件设置这些变量。

## 运行服务器

直接使用 `uv` 运行 Graphiti MCP 服务器：

bash
uv run graphiti_mcp_server.py


带选项运行：

bash
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 设置之前，您需要配置环境变量。您有两个选项：

1. **使用 .env 文件**（推荐）：
   - 复制提供的 `.env.example` 文件以创建一个 `.env` 文件：
     bash
     cp .env.example .env
     
   - 编辑 `.env` 文件以设置您的 OpenAI API 密钥和其他配置选项：
     
     # LLM 操作所需
     OPENAI_API_KEY=your_openai_api_key_here
     MODEL_NAME=gpt-4.1-mini
     # 可选：仅在非标准 OpenAI 终端节点时需要 OPENAI_BASE_URL
     # OPENAI_BASE_URL=https://api.openai.com/v1
     
   - 如果存在此文件，Docker Compose 设置将被配置为使用它（它是可选的）

2. **直接使用环境变量**：
   - 您也可以在运行 Docker Compose 命令时设置环境变量：
     bash
     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 启动服务：

bash
docker compose up


如果您使用的是较旧版本的 Docker Compose：

bash
docker-compose up


这将同时启动 Neo4j 数据库和 Graphiti MCP 服务器。Docker 设置：

- 使用 `uv` 进行包管理和运行服务器
- 从 `pyproject.toml` 文件中安装依赖项
- 使用环境变量连接到 Neo4j 容器
- 在端口 8000 上公开服务器以进行基于 HTTP 的 SSE 传输
- 包含 Neo4j 的健康检查，以确保其在启动 MCP 服务器前完全运行

## 与 MCP 客户端集成

### 配置

要将 Graphiti MCP 服务器与兼容 MCP 的客户端一起使用，请配置客户端以连接到服务器：

> [!IMPORTANT]
> 您需要安装 Python 包管理器 `uv`。请参阅 [`uv` 安装说明](https://docs.astral.sh/uv/getting-started/installation/)。
>
> 确保设置了 `uv` 二进制文件的完整路径以及您的 Graphiti 项目文件夹。

json
{
  "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），您可以使用以下配置：

json
{
  "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"
)


## 与Cursor IDE集成

要将Graphiti MCP服务器与Cursor IDE集成，请按照以下步骤操作：

1. 使用SSE传输运行Graphiti MCP服务器：

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


提示：指定`group_id`以命名空间图数据。如果您不指定`group_id`，服务器将使用"default"作为`group_id`。

或者

bash
docker compose up


2. 配置Cursor以连接到Graphiti MCP服务器。

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


3. 将Graphiti规则添加到Cursor的用户规则中。详情请参见[cursor_rules.md](cursor_rules.md)。

4. 在Cursor中启动代理会话。

该集成使Cursor中的AI助手能够通过Graphiti的知识图谱功能保持持久记忆。

## 与Claude Desktop集成（Docker MCP服务器）

Graphiti MCP服务器容器使用SSE MCP传输。Claude Desktop原生不支持SSE，因此您需要使用像`mcp-remote`这样的网关。

1. **使用SSE传输运行Graphiti MCP服务器**：

  …