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

1. 安装 Graphiti 前提条件。

2. 配置 Claude、Cursor 或其他 MCP 客户端以使用 带有 stdio 传输的 Graphiti。请参阅客户端文档以了解其 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 安装说明。

确保设置了 uv 二进制文件的完整路径以及您的 Graphiti 项目文件夹。

json
{
"mcpServers": {
"graphiti-memory": {
"transport": "stdio",
"command": "/Users//.local/bin/uv",
"args": [
"run",
"--isolated",
"--directory",
"/Users//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

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

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

1. 将Graphiti规则添加到Cursor的用户规则中。详情请参见cursor_rules.md。

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

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

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

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

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

   bash
   docker compose up

2. (可选) 全局安装mcp-remote：
   如果您希望全局安装mcp-remote，或者遇到npx无法获取包的问题，您可以全局安装它。否则，npx（在下一步中使用）将为您处理。

   bash
   npm install -g mcp-remote

3. 配置Claude Desktop：
   打开您的Claude Desktop配置文件（通常是claude_desktop_config.json），并按如下方式添加或修改mcpServers部分：

   json
   {
   "mcpServers": {
   "graphiti-memory": {
   // 您可以选择不同的名称
   "command": "npx", // 或者如果npx不在您的PATH中，则使用mcp-remote的完整路径
   "args": [
   "mcp-remote",
   "http://localhost:8000/sse" // 确保这与您的Graphiti服务器的SSE端点匹配
   ]
   }
   }
   }

   如果您已经有mcpServers条目，请在其中添加graphiti-memory（或您选择的名称）作为新的键。

4. 重启Claude Desktop 以使更改生效。

要求

• Python 3.10或更高版本
• Neo4j数据库（要求版本5.26或更高）
• OpenAI API密钥（用于LLM操作和嵌入）
• 支持MCP的客户端

许可证

本项目遵循与父级Graphiti项目相同的许可证。