Graphiti FastMCP服务器

基于泽普团队。 该项目基于 Graphiti MCP服务器来自官方Graphiti存储库。

图形是一个用于构建和查询时间感知知识图的框架，专为在动态环境中运行的AI代理量身定制。与传统的检索增强生成（RAG）方法不同，Graphiti不断地将用户交互、结构化和非结构化企业数据以及外部信息集成到一个连贯的、可查询的图中。该框架支持增量数据更新、高效检索和精确的历史查询，而不需要完整的图重新计算。

该项目是MCP服务器目录的重点副本，对生产使用和AI代理学习进行了增强。它通过模型上下文协议（MCP）公开了Graphiti的关键功能，允许AI助手与知识图功能进行交互。

有什么不同

此实现通过以下方式扩展了原始Graphiti MCP服务器：

增强	描述
FastMCP库	使用独立 `fastmcp` 库而不是MCP SDK的内置实现
FalkorDB云支持	已添加 `username` FalkorDB Cloud身份验证的配置属性
AI代理学习资源	帮助代理有效学习Graphiti的渐进式示例和文档
灾难恢复	通过导出/导入脚本对代理内存进行简单的备份/还原过程

快速入门资源

QUICKSTART.md -新Claude实例的5分钟指南
示例/ -渐进式MCP客户端示例
参考/图形_数据库_政策.md -剧集设计与知识图谱模式
文档/工厂_图案_已完成.md -工厂模式实施和部署指南

版本说明：此项目被固定到 graphiti-core==0.24.1 以确保兼容性。 生产入口点：使用 src/server.py:create_server 用于FastMCP云部署（工厂模式）。

特性

Graphiti MCP服务器提供全面的知识图功能：

事件管理：添加、检索和删除剧集（文本、消息或JSON数据）
实体管理：搜索和管理知识图中的实体节点和关系
搜索功能：使用语义和混合搜索搜索事实（边）和节点摘要
组管理：使用group_id过滤组织和管理相关数据组
图形维护：清除图形并重建索引
图形数据库支持：多种后端选项，包括FalkorDB（默认）和Neo4j
多个LLM提供商：支持OpenAI、Anthropic、Gemini、Groq和Azure OpenAI
多个嵌入提供程序：支持OpenAI、Voyage、句子转换和Gemini嵌入
丰富的实体类型：内置实体类型，包括首选项、要求、程序、位置、事件、组织、文档等，用于结构化知识提取
HTTP传输：默认HTTP传输，MCP端点位于 /mcp/ 实现广泛的客户端兼容性
基于队列的处理：具有可配置并发限制的异步事件处理

快速开始

克隆Graphiti GitHub仓库

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

或

gh repo clone getzep/graphiti

适用于Claude Desktop和其他 `stdio` 仅限客户

cd graphiti && pwd

安装 Graphiti先决条件.

配置Claude、Cursor或其他MCP客户端以使用带a的图形 stdio 运输。请参阅客户文档，了解在哪里可以找到他们的MCP配置文件。

适用于Cursor和其他启用HTTP的客户端

将目录更改为 mcp_server 目录

cd graphiti/mcp_server

使用Docker Compose启动组合的FalkorDB+MCP服务器（推荐）

docker compose up

这将在单个容器中启动FalkorDB和MCP服务器。

替代：使用Neo4j使用单独的容器运行：

docker compose -f docker/docker-compose-neo4j.yml up

将您的MCP客户端指向 http://localhost:8000/mcp/

安装

先决条件

Docker和Docker Compose（用于默认的FalkorDB设置）
用于LLM操作的OpenAI API密钥（或用于其他支持的LLM提供程序的API密钥）
（可选）如果使用外部FalkorDB实例独立运行MCP服务器，则使用Python 3.10+

设置

克隆存储库并导航到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

# Optional: Install additional LLM providers (anthropic, gemini, groq, voyage, sentence-transformers)
uv sync --extra providers

配置

服务器可以使用配置 config.yaml 文件、环境变量或命令行参数（按优先级顺序）。

默认配置

MCP服务器具有合理的默认值：

运输：HTTP（可在以下网址访问 http://localhost:8000/mcp/)
数据库：FalkorDB（与MCP服务器组合在单个容器中）
LLM：带有gpt-5-mini模型的OpenAI
嵌入器：OpenAI文本嵌入3-small

数据库配置

Falkordb（默认）

FalkorDB是一个基于Redis的图数据库，与MCP服务器捆绑在一个Docker容器中。这是默认和推荐的设置。

database:
  provider: "falkordb"  # Default
  providers:
    falkordb:
      uri: "redis://localhost:6379"
      password: ""  # Optional
      database: "default_db"  # Optional

Neo4j

对于生产使用或需要全功能图形数据库时，建议使用Neo4j：

database:
  provider: "neo4j"
  providers:
    neo4j:
      uri: "bolt://localhost:7687"
      username: "neo4j"
      password: "your_password"
      database: "neo4j"  # Optional, defaults to "neo4j"

FalkorDB 的

FalkorDB是另一个基于Redis的图形数据库选项：

database:
  provider: "falkordb"
  providers:
    falkordb:
      uri: "redis://localhost:6379"
      password: ""  # Optional
      database: "default_db"  # Optional

配置文件（config.yaml）

该服务器支持多个LLM提供者（OpenAI、Anthropic、Gemini、Groq）和嵌入器。编辑 config.yaml 配置：

server:
  transport: "http"  # Default. Options: stdio, http

llm:
  provider: "openai"  # or "anthropic", "gemini", "groq", "azure_openai"
  model: "gpt-4.1"  # Default model

database:
  provider: "falkordb"  # Default. Options: "falkordb", "neo4j"

使用Olama进行本地LLM

要将Ollama与MCP服务器一起使用，请将其配置为OpenAI兼容的端点：

llm:
  provider: "openai"
  model: "gpt-oss:120b"  # or your preferred Ollama model
  api_base: "http://localhost:11434/v1"
  api_key: "ollama"  # dummy key required

embedder:
  provider: "sentence_transformers"  # recommended for local setup
  model: "all-MiniLM-L6-v2"

确保Ollama在本地运行： ollama serve

实体类型

Graphiti MCP Server包括用于结构化知识提取的内置实体类型。这些实体类型始终通过启用和配置 entity_types 你的部分 config.yaml:

可用实体类型：

偏好：用户偏好、选择、意见或选择（根据用户特定信息进行优先级排序）
需求要求
规格：必须满足的特定需求、特性或功能
程序：标准操作程序和顺序说明
位置：活动发生的物理或虚拟场所
事件：有时限的活动、事件或经历
组织：公司、机构、团体或正式实体
文档：各种形式的信息内容（书籍、文章、报告、视频等）
主题：对话、兴趣或知识领域的主题（用作后备）

对象 config.yaml ：实物、工具、设备或财产（用作后备）

graphiti:
  entity_types:
    - name: "Preference"
      description: "User preferences, choices, opinions, or selections"
    - name: "Requirement"
      description: "Specific needs, features, or functionality"
    # ... additional entity types

这些实体类型在

并且可以通过修改描述来定制：

MCP服务器在事件摄取期间自动使用这些实体类型来从对话和文档中提取和构建信息。 config.yaml 环境变量 ${VAR_NAME} 这 ${VAR_NAME:default} 文件支持使用以下方式扩展环境变量

NEO4J_URI或 bolt://localhost:7687语法。关键变量：
NEO4J_USER：Neo4j数据库的URI（默认值： neo4j)
NEO4J_PASSWORD：Neo4j用户名（默认值： demodemo)
OPENAI_API_KEY：Neo4j密码（默认值：
ANTHROPIC_API_KEY)
GOOGLE_API_KEY：OpenAI API密钥（对于OpenAI LLM/embedder是必需的）
GROQ_API_KEY：Anthropic API钥匙（适用于Claude车型）
AZURE_OPENAI_API_KEY：Google API密钥（适用于Gemini型号）
AZURE_OPENAI_ENDPOINT：Groq API密钥（用于Groq模型）
AZURE_OPENAI_DEPLOYMENT：Azure OpenAI API密钥
AZURE_OPENAI_EMBEDDINGS_ENDPOINT：Azure OpenAI端点URL
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT：Azure OpenAI部署名称
AZURE_OPENAI_API_VERSION：可选的Azure OpenAI嵌入端点URL
USE_AZURE_AD：可选的Azure OpenAI嵌入部署名称
SEMAPHORE_LIMIT：可选Azure OpenAI API版本：可选使用Azure托管身份进行身份验证

：事件处理并发性。看 .env 并发和LLM提供程序429速率限制错误

您可以在

项目目录中的文件。

运行服务器

docker compose up

默认设置（FalkorDB组合容器）

要使用默认的FalkorDB设置运行Graphiti MCP服务器： http://localhost:8000/mcp/
这将以以下内容开始一个容器： localhost:6379
HTTP传输打开 http://localhost:3000
FalkorDB图形数据库

FalkorDB 网页界面

OpenAI LLM与gpt-5-mini模型

使用Neo4j运行

# This starts both Neo4j and the MCP server
docker compose -f docker/docker-compose.neo4j.yaml up

选项1：使用Docker Compose

使用Neo4j运行的最简单方法是使用提供的Docker Compose配置：

# Set environment variables
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your_password"

# Run with Neo4j
uv run graphiti_mcp_server.py --database-provider neo4j

选项2：使用现有的Neo4j直接执行

uv run graphiti_mcp_server.py --config config/config-docker-neo4j.yaml

如果你已经在运行Neo4j：

或者使用Neo4j配置文件：

# This starts both FalkorDB (Redis-based) and the MCP server
docker compose -f docker/docker-compose.falkordb.yaml up

使用FalkorDB运行

# Set environment variables
export FALKORDB_URI="redis://localhost:6379"
export FALKORDB_PASSWORD=""  # If password protected

# Run with FalkorDB
uv run src/graphiti_mcp_server.py --database-provider falkordb

选项1：使用Docker Compose

uv run graphiti_mcp_server.py --config config/config-docker-falkordb.yaml

选项2：使用现有的FalkorDB直接执行

--config或者使用FalkorDB配置文件：
--llm-provider可用的命令行参数
--embedder-provider：YAML配置文件的路径（默认：config.YAML）
--database-provider：要使用的LLM提供程序（openai、anthropic、gemini、groq、azure \_openai）
--model：要使用的嵌入器提供程序（openai、azure \_openai、gemini、voyage）
--temperature：要使用的数据库提供程序（falkordb，neo4j）-默认值：falkordb
--transport：与LLM客户端一起使用的模型名称
--group-id：LLM的温度设置（0.0-2.0）
--destroy-graph：选择传输方式（http或stdio，默认：http）

：为图形设置命名空间（可选）。如果未提供，则默认为“main”

：如果设置，则在启动时销毁所有Graphiti图形 SEMAPHORE_LIMIT 并发和LLM提供程序429速率限制错误

Graphiti的摄取管道设计用于高并发性，由 SEMAPHORE_LIMIT=10 环境变量。此设置决定可以同时处理多少集。由于每一集都涉及多个LLM调用（实体提取、重复数据删除、摘要），因此并发LLM请求的实际数量将高出数倍。

违约：

（适用于OpenAI Tier 3、中端Anthropic）

LLM提供商的调优指南 SEMAPHORE_LIMIT=1-2
OpenAI： SEMAPHORE_LIMIT=5-8
1级（免费）：3转/分→ SEMAPHORE_LIMIT=10-15
第二级：60转/分→ SEMAPHORE_LIMIT=20-50

第三级：500转/分→

第4级：5000转/分→ SEMAPHORE_LIMIT=5-8
人类学： SEMAPHORE_LIMIT=15-30

默认层：50 RPM→

高端：1000转/分→
Azure OpenAI：

请咨询Azure门户中的配额并相应调整

从保守开始，逐渐增加 SEMAPHORE_LIMIT=1-5
奥利玛（当地）：

取决于硬件→

监控CPU/GPU使用情况并进行调整症状
太高了：429个速率限制错误，并行处理增加了API成本

过低

：剧集吞吐量缓慢，API配额未得到充分利用 429 监控
查看日志
速率限制误差
监控服务器日志中的事件处理时间

查看LLM提供商的仪表板，了解实际申请率 .env 跟踪代币使用和成本

SEMAPHORE_LIMIT=10  # Adjust based on your LLM provider tier

在您的

文件： uv Docker部署

Graphiti MCP服务器可以使用Docker部署，您可以选择数据库后端。Dockerfile使用 zepai/knowledge-graph-mcp

对于包管理，确保一致的依赖关系安装。

预构建的Graphiti MCP容器可在以下网址获得： .env 环境配置

在运行Docker Compose之前，请使用文件（推荐）：

   cd graphiti/mcp_server
   cp .env.example .env

在mcp_server目录中创建.env文件 :

   # Required - at least one LLM provider API key
   OPENAI_API_KEY=your_openai_api_key_here

   # Optional - other LLM providers
   ANTHROPIC_API_KEY=your_anthropic_key
   GOOGLE_API_KEY=your_google_key
   GROQ_API_KEY=your_groq_key

   # Optional - embedder providers
   VOYAGE_API_KEY=your_voyage_key

编辑.env文件设置API密钥： .env 重要 mcp_server/ ：The docker/ 文件必须位于

子目录）。 mcp_server 使用Docker Compose运行 所有命令都必须从 .env 目录

cd graphiti/mcp_server

以确保

文件已正确加载：

docker compose up

选项1:FalkorDB组合容器（默认）

具有FalkorDB和MCP服务器的单个容器-最简单的选择：

docker compose -f docker/docker-compose-neo4j.yml up

选项2:Neo4j数据库

使用Neo4j和MCP服务器分离容器： neo4j
默认Neo4j凭据： demodemo
用户名： bolt://neo4j:7687
密码： http://localhost:7474

螺栓URI：

浏览器用户界面：

docker compose -f docker/docker-compose-falkordb.yml up

选项3：带单独容器的FalkorDB

使用单独的FalkorDB和MCP服务器容器的替代设置： 6379
FalkorDB配置： http://localhost:3000
Redis端口： redis://falkordb:6379

Web用户界面：

连接：

访问MCP服务器运行后，MCP服务器可在以下位置使用： http://localhost:8000/mcp/
HTTP端点: http://localhost:8000/health

健康检查

: docker/ 从其他目录运行Docker Compose mcp_server/如果你从以下位置运行Docker Compose .env 子目录而不是

# Change this line in the docker-compose file:
env_file:
  - path: ../.env    # When running from mcp_server/

# To this:
env_file:
  - path: .env       # When running from mcp_server/docker/

，您需要修改 组合文件中的文件路径： mcp_server/ 然而， 从奔跑

备注

：对于FastMCP Cloud部署，请使用入口点

add_memory可用工具
search_nodesGraphiti MCP服务器公开了以下工具：
search_memory_facts：将一集添加到知识图中（支持文本、JSON和消息格式）-排队等待异步处理
get_episodes：在知识图中搜索相关节点摘要
get_entity_edge：在知识图中搜索相关事实（实体之间的边）
delete_episode：获取特定组的最新剧集
delete_entity_edge：通过UUID获取实体边
clear_graph：从知识图中删除一集
get_status：从知识图中删除实体边

：清除知识图中的所有数据并重建索引

：获取Graphiti MCP服务器和数据库连接的状态 add_memory 使用JSON数据 source="json"Graphiti MCP服务器可以通过工具与

add_memory(
    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集成

uv run graphiti_mcp_server.py --group-id

要将Graphiti MCP服务器与Cursor IDE集成，请执行以下步骤： group_id 使用默认HTTP传输运行Graphiti MCP服务器： group_id提示：指定

到名称空间图数据。如果不指定

docker compose up

，服务器将使用“main”作为group_id。

{
  "mcpServers": {
    "graphiti-fastmcp": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

或配置Cursor以连接到Graphiti MCP服务器。将Graphici规则添加到Cursor的用户规则中。看

cursor_rules.md

了解详情。在Cursor中启动代理会话。

该集成使Cursor中的AI助手能够通过Graphiti的知识图来维护持久内存

能力。 /mcp/与Claude Desktop（Docker MCP服务器）集成 mcp-remoteGraphiti MCP服务器使用HTTP传输（在端点

).Claude Desktop本身不支持HTTP传输，因此您需要使用类似的网关.

   docker compose up
   # Or run directly with uv:
   uv run graphiti_mcp_server.py

运行Graphiti MCP服务器 mcp-remote :（可选）安装

全球范围内 mcp-remote : npx 如果你喜欢 npx 全局安装，或者如果您遇到以下问题

   npm install -g mcp-remote

获取包后，您可以全局安装它。否则，（在下一步中使用）将为您处理。

配置Claude桌面 claude_desktop_config.json: mcpServers 打开Claude Desktop配置文件（通常

   {
     "mcpServers": {
       "graphiti-fastmcp": {
         // 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/mcp/" // The Graphiti server's HTTP endpoint
         ]
       }
     }
   }

)并添加或修改 mcpServers 章节如下： graphiti-fastmcp 如果你已经有了

条目，添加 （或您选择的名称）作为其中的新密钥。

重新启动克劳德桌面

以使更改生效。
需求
Python 3.10或更高版本
OpenAI API密钥（用于LLM操作和嵌入）或其他LLM提供程序API密钥
MCP兼容客户端

Docker和Docker Compose（用于默认的FalkorDB组合容器）

（可选）Neo4j数据库（5.26或更高版本）（如果不使用默认的FalkorDB设置）

遥测

Graphiti MCP服务器使用Graphiti核心库，其中包括匿名遥测收集。初始化Graphiti MCP服务器时，会收集匿名使用统计数据以帮助改进框架。
收集了什么
匿名标识符和系统信息（操作系统、Python版本）

Graphiti版本和配置选项（LLM提供者、数据库后端、嵌入器类型）

从未收集过任何个人数据、API密钥或实际图形内容

export GRAPHITI_TELEMETRY_ENABLED=false

如何禁用 .env 要禁用MCP服务器中的遥测，请设置环境变量：

GRAPHITI_TELEMETRY_ENABLED=false

或者将其添加到您的文件：有关收集内容和原因的完整详细信息，请参阅

主Graphiti README中的遥测部分

. 许可证此项目根据Apache许可证2.0获得许可-请参阅

许可证文件以获取详细信息。此许可证与父许可证相同

Graphiti Fastmcp

快速接入

详细介绍