MCP服务器

Name: MCP服务器
Author: getzep

作者：getzep20390 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

Graphiti MCP Server

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

这是一个针对 Graphiti 的实验性模型上下文协议（MCP）服务器实现。MCP 服务器通过 MCP 协议暴露 Graphiti 的核心功能，允许 AI 助手与 Graphiti 的知识图谱能力进行交互。

特性

Graphiti MCP 服务器提供了全面的知识图谱能力：

会话管理：添加、检索和删除会话（文本、消息或 JSON 数据）
实体管理：搜索和管理知识图谱中的实体节点和关系
搜索能力：使用语义和混合搜索来查找事实（边）和节点摘要
分组管理：使用 group_id 过滤器组织和管理相关数据的分组
图维护：清除图并重建索引
图数据库支持：多种后端选项，包括 FalkorDB（默认）和 Neo4j
多个大语言模型提供商：支持 OpenAI、Anthropic、Gemini、Groq 和 Azure OpenAI
多个嵌入提供商：支持 OpenAI、Voyage、Sentence Transformers 和 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 客户端以使用 [Graphiti 和 stdio 传输](#集成到 MCP 客户端)。查看客户端文档以了解如何找到其 MCP 配置文件的位置。

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

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 设置）
OpenAI API 密钥（用于大语言模型操作）或其他支持的大语言模型提供商的 API 密钥
（可选）Python 3.10+（如果独立运行 MCP 服务器并与外部 FalkorDB 实例结合）

设置

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

# 如果还没有安装 uv，请先安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在一步中创建虚拟环境并安装依赖项
uv sync

# 可选：安装额外的大语言模型提供商（anthropic, gemini, groq, voyage, sentence-transformers）
uv sync --extra providers

配置

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

默认配置

MCP 服务器带有合理的默认设置：

传输：HTTP（可通过 http://localhost:8000/mcp/ 访问）
数据库：FalkorDB（与 MCP 服务器一起捆绑在单个容器中）
大语言模型：OpenAI，使用模型 gpt-5-mini
嵌入器：OpenAI text-embedding-3-small

数据库配置

FalkorDB（默认）

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

database:
  provider: "falkordb"  # 默认
  providers:
    falkordb:
      uri: "redis://localhost:6379"
      password: ""  # 可选
      database: "default_db"  # 可选

Neo4j

对于生产用途或需要全功能图数据库的情况，推荐使用 Neo4j：

database:
  provider: "neo4j"
  providers:
    neo4j:
      uri: "bolt://localhost:7687"
      username: "neo4j"
      password: "your_password"
      database: "neo4j"  # 可选，默认为 "neo4j"

FalkorDB

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

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

配置文件（config.yaml）

服务器支持多个大语言模型提供商（OpenAI、Anthropic、Gemini、Groq）和嵌入器。编辑 config.yaml 来配置：

server:
  transport: "http"  # 默认。选项：stdio, http

llm:
  provider: "openai"  # 或 "anthropic", "gemini", "groq", "azure_openai"
  model: "gpt-4.1"  # 默认模型

database:
  provider: "falkordb"  # 默认。选项："falkordb", "neo4j"

使用 Ollama 作为本地大语言模型

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

llm:
  provider: "openai"
  model: "gpt-oss:120b"  # 或您首选的 Ollama 模型
  api_base: "http://localhost:11434/v1"
  api_key: "ollama"  # 需要的假密钥

embedder:
  provider: "sentence_transformers"  # 推荐用于本地设置
  model: "all-MiniLM-L6-v2"

确保本地运行 Ollama：ollama serve

实体类型

Graphiti MCP 服务器包括用于结构化知识提取的内置实体类型。这些实体类型始终启用，并通过 config.yaml 中的 entity_types 部分进行配置：

可用实体类型：

偏好：用户偏好、选择、意见或选择（优先考虑用户特定信息）
需求：必须满足的具体需求、功能或特性
程序：标准操作程序和顺序指令
地点：活动发生的物理或虚拟场所
事件：有时间限制的活动、发生或体验
组织：公司、机构、团体或正式实体
文档：各种形式的信息内容（书籍、文章、报告、视频等）
主题：对话的主题、兴趣或知识领域（用作回退）
对象：物理物品、工具、设备或财产（用作回退）

这些实体类型定义在 config.yaml 中，并可通过修改描述来进行定制：

graphiti:
  entity_types:
    - name: "偏好"
      description: "用户偏好、选择、意见或选择"
    - name: "需求"
      description: "具体需求、功能或特性"
    # ... 其他实体类型

MCP 服务器在会话摄入期间自动使用这些实体类型，从对话和文档中提取和结构化信息。

环境变量

config.yaml 文件支持使用 ${VAR_NAME} 或 ${VAR_NAME:default} 语法进行环境变量扩展。关键变量：

NEO4J_URI：Neo4j 数据库的 URI（默认：bolt://localhost:7687）
NEO4J_USER：Neo4j 用户名（默认：neo4j）
NEO4J_PASSWORD：Neo4j 密码（默认：demodemo）
OPENAI_API_KEY：OpenAI API 密钥（使用 OpenAI 大语言模型/嵌入器时必需）
ANTHROPIC_API_KEY：Anthropic API 密钥（用于 Claude 模型）
GOOGLE_API_KEY：Google API 密钥（用于 Gemini 模型）
GROQ_API_KEY：Groq API 密钥（用于 Groq 模型）
AZURE_OPENAI_API_KEY：Azure OpenAI API 密钥
AZURE_OPENAI_ENDPOINT：Azure OpenAI 终端 URL
AZURE_OPENAI_DEPLOYMENT：Azure Open- AI 部署名称
AZURE_OPENAI_EMBEDDINGS_ENDPOINT：可选的 Azure OpenAI 嵌入终端 URL
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT：可选的 Azure OpenAI 嵌入部署名称
AZURE_OPENAI_API_VERSION：可选的 Azure OpenAI API 版本
USE_AZURE_AD：可选地使用 Azure 管理的身份验证标识
SEMAPHORE_LIMIT：会话处理并发。参见 [并发和大语言模型提供商 429 速率限制错误](#并发和大语言模型提供商 429 速率限制错误)

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

运行服务器

默认设置（FalkorDB 组合容器）

要使用默认的 FalkorDB 设置运行 Graphiti MCP 服务器：

docker compose up

这将启动一个容器，其中包括：

HTTP 传输在 http://localhost:8000/mcp/
在 localhost:6379 上的 FalkorDB 图数据库
在 http://localhost:3000 上的 FalkorDB Web UI
使用 gpt-5-mini 模型的 OpenAI 大语言模型

使用 Neo4j 运行

选项 1：使用 Docker Compose

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

# 这将启动 Neo4j 和 MCP 服务器
docker compose -f docker/docker-compose.neo4j.yaml up

选项 2：直接执行现有 Neo4j

如果您已经运行了 Neo4j：

# 设置环境变量
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your_password"

# 使用 Neo4j 运行
uv run graphiti_mcp_server.py --database-provider neo4j

或者使用 Neo4j 配置文件：

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

使用 FalkorDB 运行

选项 1：使用 Docker Compose

# 这将启动 FalkorDB（基于 Redis）和 MCP 服务器
docker compose -f docker/docker-compose.falkordb.yaml up

选项 2：直接执行现有 FalkorDB

# 设置环境变量
export FALKORDB_URI="redis://localhost:6379"
export FALKORDB_PASSWORD=""  # 如果受密码保护

# 使用 FalkorDB 运行
uv run graphiti_mcp_server.py --database-provider falkordb

或者使用 FalkorDB 配置文件：

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

可用的命令行参数

--config：YAML 配置文件的路径（默认：config.yaml）
--llm-provider：要使用的大型语言模型提供商（openai, anthropic, gemini, groq, azure_openai）
--embedder-provider：要使用的嵌入器提供商（openai, azure_openai, gemini, voyage）
--database-provider：要使用的数据库提供商（falkordb, neo4j）- 默认：falkordb
--model：要与大型语言模型客户端一起使用的模型名称
--temperature：大型语言模型的温度设置（0.0-2.0）
--transport：选择传输方法（http 或 stdio，默认：http）
--group-id：为图设置命名空间（可选）。如果没有提供，则默认为 "main"
--destroy-graph：如果设置，将在启动时销毁所有 Graphiti 图

并发和大语言模型提供商 429 速率限制错误

Graphiti 的摄入管道设计用于高并发，由 SEMAPHORE_LIMIT 环境变量控制。此设置决定了可以同时处理多少个会话。由于每个会话涉及多次大型语言模型调用（实体提取、去重、总结），实际的并发大型语言模型请求数量将是几倍之多。

默认值：SEMAPHORE_LIMIT=10（适合 OpenAI 第 3 层，中档 Anthropic）

根据大型语言模型提供商调整指南

OpenAI：

第 1 层（免费）：3 RPM → SEMAPHORE_LIMIT=1-2
第 2 层：60 RPM → SEMAPHORE_LIMIT=5-8
第 3 层：500 RPM → SEMAPHORE_LIMIT=10-15
第 4 层：5,000 RPM → SEMAPHORE_LIMIT=20-50

Anthropic：

默认层：50 RPM → SEMAPHORE_LIMIT=5-8
高层：1,000 RPM → SEMAPHORE_LIMIT=15-30

Azure OpenAI：

查看 Azure 门户中的配额并相应调整
从保守开始并逐渐增加

Ollama（本地）：

硬件依赖 → SEMAPHORE_LIMIT=1-5
监控 CPU/GPU 使用情况并调整

症状

过高：429 速率限制错误，因并行处理而增加的 API 成本
过低：会话吞吐量慢，API 配额利用率不足

监控

查看日志中的 429 速率限制错误
监控服务器日志中的会话处理时间
检查您的大型语言模型提供商仪表板的实际请求率
跟踪令牌使用情况和成本

在您的 .env 文件中设置：

SEMAPHORE_LIMIT=10  # 根据您的大型语言模型提供商层级调整

Docker 部署

Graphiti MCP 服务器可以使用 Docker 部署，选择您喜欢的数据库后端。Dockerfile 使用 uv 进行包管理，确保一致的依赖项安装。

预构建的 Graphiti MCP 容器可在以下位置获得：zepai/knowledge-graph-mcp

环境配置

在运行 Docker Compose 之前，使用 .env 文件（推荐）配置您的 API 密钥：

在 mcp_server 目录中创建一个 .env 文件：
```
cd graphiti/mcp_server
cp .env.example .env
```

编辑 .env 文件以设置您的 API 密钥：

# 至少需要一个大型语言模型提供商的 API 密钥
OPENAI_API_KEY=your_openai_api_key_here

# 其他大型语言模型提供商（可选）
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key
GROQ_API_KEY=your_groq_key

# 嵌入器提供商（可选）
VOYAGE_API_KEY=your_voyage_key

重要：.env 文件必须位于 mcp_server/ 目录中（docker/ 子目录的父目录）。

使用 Docker Compose 运行

所有命令都必须从 mcp_server 目录运行，以确保正确加载 .env 文件：

cd graphiti/mcp_server

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

单个容器，包含 FalkorDB 和 MCP 服务器 - 最简单的选项：

docker compose up

选项 2：Neo4j 数据库

分离容器，包含 Neo4j 和 MCP 服务器：

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

默认 Neo4j 凭证：

用户名：neo4j
密码：demodemo
Bolt URI：bolt://neo4j:7687
浏览器 UI：http://localhost:7474

选项 3：FalkorDB 分离容器

另一种设置，包含分离的 FalkorDB 和 MCP 服务器容器：

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

FalkorDB 配置：

Redis

MCP服务器

项目介绍

Graphiti MCP Server

特性

快速开始

克隆 Graphiti GitHub 仓库

对于 Claude Desktop 和其他仅支持 stdio 的客户端

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

安装

预备条件

设置

配置

默认配置

数据库配置

FalkorDB（默认）

Neo4j

FalkorDB

配置文件（config.yaml）

使用 Ollama 作为本地大语言模型

实体类型

环境变量

运行服务器

默认设置（FalkorDB 组合容器）

使用 Neo4j 运行

选项 1：使用 Docker Compose

选项 2：直接执行现有 Neo4j

使用 FalkorDB 运行

选项 1：使用 Docker Compose

选项 2：直接执行现有 FalkorDB

可用的命令行参数

并发和大语言模型提供商 429 速率限制错误

根据大型语言模型提供商调整指南

症状

监控

Docker 部署

环境配置

使用 Docker Compose 运行

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

选项 2：Neo4j 数据库

选项 3：FalkorDB 分离容器

对于 Claude Desktop 和其他仅支持 `stdio` 的客户端