Graphiti MCP 服务器

Graphiti 是一个用于构建和查询时序感知知识图谱的框架，专为在动态环境中运行的 AI 代理量身定制。与传统的检索增强生成 (RAG) 方法不同，Graphiti 持续将用户交互、结构化和非结构化企业数据以及外部信息集成到一个连贯且可查询的图中。该框架支持增量数据更新、高效检索和精确的历史查询，无需完全重新计算图谱，因此非常适合开发交互式、情境感知的 AI 应用程序。

这是 Graphiti 的一个实验性模型上下文协议 (MCP) 服务器实现。MCP 服务器通过 MCP 协议公开 Graphiti 的关键功能，允许 AI 助手与 Graphiti 的知识图谱功能进行交互。

特征

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

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

Related MCP server: Alchemy MCP Server

Claude Desktop、Cursor 和其他客户端的快速入门

克隆 Graphiti GitHub 仓库

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

或者

gh repo clone getzep/graphiti

请记下该目录的完整路径。

cd graphiti && pwd

安装Graphiti 先决条件。
配置 Claude、Cursor 或其他 MCP 客户端，使其能够通过。请参阅客户端文档，了解其 MCP 配置文件的所在位置。

安装

先决条件

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

设置

克隆存储库并导航到 mcp_server 目录
使用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 托管身份进行身份验证

您可以在项目目录中的.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 设置之前，您需要配置环境变量。您有两个选择：

使用 .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 设置将使用此文件（可选）

直接使用环境变量：
- 您还可以在运行 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 容器
将服务器暴露在端口 8000 上，以进行基于 HTTP 的 SSE 传输
包括 Neo4j 的健康检查，以确保其在启动 MCP 服务器之前完全正常运行

与 MCP 客户端集成

配置

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

重要提示：你需要安装 Python 包管理器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"
)

与 Cursor IDE 集成

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

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

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

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

或者

docker compose up

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

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

将 Graphiti 规则添加到 Cursor 的用户规则中。详情请参阅cursor_rules.md 。
在 Cursor 中启动代理会话。

通过集成，Cursor 中的 AI 助手能够通过 Graphiti 的知识图谱功能维护持久内存。

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

Graphiti MCP Server 容器使用 SSE MCP 传输。Claude Desktop 本身不支持 SSE，因此您需要使用类似mcp-remote的网关。

使用 SSE 传输运行 Graphiti MCP 服务器：
```
docker compose up
```
（可选）全局安装 ：如果您希望全局安装mcp-remote ，或者在使用npx获取包时遇到问题，则可以全局安装。否则， npx （下一步使用）将为您处理。
```
npm install -g mcp-remote
```

配置 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 （或您选择的名称）作为新键。

重新启动 Claude Desktop以使更改生效。

要求

Python 3.10 或更高版本
Neo4j 数据库（需要 5.26 或更高版本）
OpenAI API 密钥（用于 LLM 操作和嵌入）
MCP 兼容客户端

执照

该项目与母公司 Graphiti 项目采用相同的许可。

Graphiti MCP Server