AI导哈

知识图谱服务器

Graphiti MCP Server是一个用于构建和查询时间感知知识图谱的框架，专为动态环境中的AI代理设计，支持增量数据更新、高效检索和精确历史查询。

  • by mandelbro
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 mandelbro/graphiti-memory

使用说明

石墨烯MCP服务器

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

这是一个针对Graphiti的实验性模型上下文协议（MCP）服务器实现。MCP服务器提供了（或暴露了） 通过MCP协议，Graphiti的关键功能使得AI助手能够与Graphiti的知识库进行交互 图形功能。

特点/功能

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

  • 剧集管理添加、检索和删除剧集（文本、消息或JSON数据）
  • 实体管理在知识图谱中搜索和管理实体节点及关系
  • 搜索功能使用语义搜索和混合搜索查找事实（边）和节点摘要
  • 集团管理使用group_id进行过滤，组织和管理相关数据组
  • 图维护清除图表并重建索引
  • 灵活的Ollama配置通过CLI参数和环境变量完全可配置的LLM（大型语言模型）和嵌入模型

快速入门

🚀 从 PyPI 安装（推荐）

最快的入门方式是使用 uvx 从PyPI安装并运行：

# Install and run with default settings
uvx montesmakes.graphiti-memory

# Run with custom configuration
uvx montesmakes.graphiti-memory --transport stdio --group-id my-project

📖 书籍 有关uvx的详细使用方法和配置选项，请参阅 UVXUSAGE.md（文件名，可译为“UVX使用说明.md”或保持原样，根据上下文决定是否需要翻译文件名）

🛠️ 开发安装

用于开发或直接从源代码运行：

git clone https://github.com/mandelbro/graphiti-memory.git
cd graphiti/mcp_server

或者使用 GitHub CLI：

gh repo clone mandelbro/graphiti-memory
cd graphiti/mcp_server

对于Claude Desktop及其他（产品/服务） stdio 仅限客户

  1. 记下此目录的完整路径。
cd graphiti && pwd

  1. 安装 Graphiti的先决条件。

  2. 配置Claude、Cursor或其他MCP客户端以使用 涂有石墨的（物体） stdio 运输请参阅客户端文档，了解如何找到其MCP配置文件。

对于Cursor和其他（软件/工具） sse-启用的客户端

  1. 切换目录到 mcp_server 目录

cd graphiti/mcp_server

  1. 使用 Docker Compose 启动服务

docker compose up

  1. 将您的MCP客户端指向 http://localhost:8020/sse

安装

快速入门uvx（推荐）

最快的入门方法是使用 uvx 直接运行服务器：

# Install and run with default settings
uvx montesmakes.graphiti-memory

# Run with custom configuration
uvx montesmakes.graphiti-memory --transport stdio --group-id my-project

# For detailed uvx usage, see UVXUSAGE.md

先决条件

  1. 确保已安装 Python 3.10 或更高版本。
  2. 一个正在运行的Neo4j数据库（需要5.26版本或更高版本）
  3. Ollama（注：Ollama是一个开源的机器学习框架，用于训练和部署机器学习模型，但直接翻译该名称并无固定对应中文，此处保留原英文名称） 已安装并运行（默认）或用于大型语言模型（LLM）操作的OpenAI API密钥

Ollama 设置（默认）

服务器现在默认使用Ollama进行大型语言模型（LLM）操作和嵌入处理。要设置Ollama：

  1. 安装Ollama参观 https://ollama.ai（可译为：“奥拉玛人工智能网站”或保持原样作为网址引用） 安装说明
  2. 启动Ollama跑 ollama serve 启动Ollama服务器
  3. 拉取所需模型：
    ollama pull deepseek-r1:7b     # LLM model
ollama pull nomic-embed-text   # Embedding model

服务器将自动连接到Ollama http://localhost:11434/v1 并默认使用这些模型。

OpenAI 设置（备选方案）

如果你更倾向于使用OpenAI而不是Ollama：

  1. 设置环境变量： USE_OLLAMA=false
  2. 配置您的OpenAI API密钥： OPENAI_API_KEY=your_api_key_here
  3. 可选地，使用（工具/方法）自定义模型 MODEL_NAME 并且 SMALL_MODEL_NAME 环境变量

Docker 设置

该项目包含Docker Compose配置，便于轻松部署。使用Docker配置Ollama有多种方法：

选项1：使用主机Ollama（推荐）

如果你的主机上正在运行Ollama：

  1. 在您的主机上启动Ollama:

    ollama serve

  2. 拉取所需模型：

    ollama pull deepseek-r1:7b
ollama pull nomic-embed-text

  3. 启动服务：

    docker compose up

服务器将使用（相应方法）连接到您的主机Ollama实例 host.docker.internal:11434。

注Graphiti核心库需要一个 OPENAI_API_KEY 即使在使用Ollama（用于重排序组件）时，也必须设置环境变量。Docker配置中包含一个虚拟的API密钥（abc为此目的。

选项2：使用容器化的Ollama

如果您更倾向于在容器中运行 Ollama：

  1. 取消注释Ollama服务 在 docker-compose.yml：

    ollama:
  image: ollama/ollama:latest
  ports:
    - "11434:11434"
  volumes:
    - ollama_data:/root/.ollama

  2. 更新 OLLAMA_BASE_URL 在环境部分：

    environment:
  - OLLAMA_BASE_URL=http://ollama:11434/v1

  3. 取消音量的注释（或：取消音量的注释语句）:

    volumes:
  ollama_data:

  4. 启动服务：

    docker compose up

  5. 容器中的拉模型:

    docker compose exec ollama ollama pull deepseek-r1:7b
docker compose exec ollama ollama pull nomic-embed-text

选项3：使用Docker运行OpenAI

在Docker中使用OpenAI而不是Ollama：

  1. 创建一个 .env 文件 使用您的OpenAI配置：

    USE_OLLAMA=false
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4o-mini

  2. 更新 docker-compose.yml 文件 使用 .env 文件：

    env_file:
  - .env

  3. 启动服务:

    docker compose up

本地开发环境设置

  1. 克隆仓库：

    git clone <repository-url>
cd mcp_server

  2. 安装依赖项：

    uv sync

  3. 设置环境变量 （可选）：

    cp .env.example .env
# Edit .env with your configuration

  4. 启动Neo4j （如果使用 Docker）：

    docker compose up neo4j -d

  5. 运行服务器:

    uv run src/graphiti_mcp_server.py --transport sse

配置

服务器支持多种配置方法，优先级如下（从高到低）：

  1. 命令行界面（CLI）参数 （最高优先级）
  2. 环境变量
  3. YAML 配置文件
  4. 默认值 （最低优先级）

配置方法

YAML 配置文件（推荐）

对于复杂的配置，您可以使用YAML文件在 config/ 目录：

# config/providers/ollama.yml
llm:
  model: "deepseek-r1:7b"
  base_url: "http://localhost:11434/v1"
  temperature: 0.1
  max_tokens: 8192
  model_parameters:
    num_ctx: 4096          # Context window size
    num_predict: -1        # Number of tokens to predict
    repeat_penalty: 1.1    # Penalty for repeating tokens
    top_k: 40             # Limit token selection to top K
    top_p: 0.9            # Cumulative probability cutoff

查看 config/README.md（可译为：“配置/README.md文件”或保持原样，因为文件名通常不翻译，但在这里为了说明其含义，可以这样理解） 关于YAML配置的详细信息。

环境变量

服务器使用以下环境变量：

  • NEO4J_URINeo4j 数据库的 URI（默认： bolt://localhost:7687)
  • NEO4J_USERNeo4j 用户名（默认： neo4j)
  • NEO4J_PASSWORDNeo4j 密码（默认： demodemo）

大型语言模型（LLM）配置

服务器现在默认使用 Ollama（注：这是一个专有名词或特定项目名，直接翻译为中文可能无具体含义，故保留原样） 用于大型语言模型（LLM）操作和嵌入。您可以使用以下环境变量对其进行配置：

Ollama 配置（默认）

  • USE_OLLAMA使用Ollama作为大型语言模型（LLM）和嵌入模型（默认： true)
  • OLLAMA_BASE_URLOllama 基础 URL（默认： http://localhost:11434/v1)
  • OLLAMA_LLM_MODELOllama LLM模型名称（默认： deepseek-r1:7b)
  • OLLAMA_EMBEDDING_MODELOllama 嵌入模型名称（默认： nomic-embed-text)
  • OLLAMA_EMBEDDING_DIMOllama 嵌入维度（默认： 768)
  • LLM_MAX_TOKENSLLM响应的最大标记数（默认： 8192）

Ollama模型参数： 现在，您可以配置Ollama特定的模型参数，例如 num_ctx， top_p， repeat_penalty等，使用YAML配置文件。这提供了对模型行为的细粒度控制，这是仅通过环境变量无法实现的。

OpenAI 配置（替代方案）

要使用OpenAI而不是Ollama，请设置 USE_OLLAMA=false 并进行配置：

  • OPENAI_API_KEYOpenAI API密钥（用于大型语言模型操作）
  • OPENAI_BASE_URL可选的OpenAI API基础URL
  • MODEL_NAME用于LLM操作的OpenAI模型名称（默认： gpt-4.1-mini）
  • SMALL_MODEL_NAME用于较小规模语言模型（LLM）操作的OpenAI模型名称（默认： gpt-4.1-nano)
  • LLM_TEMPERATURE大语言模型（LLM）响应的温度参数（0.0-2.0）
  • LLM_MAX_TOKENSLLM响应的最大标记数（默认： 8192)

Azure OpenAI 配置（替代方案）

要使用 Azure OpenAI，请设置 USE_OLLAMA=false 并进行配置：

  • AZURE_OPENAI_ENDPOINTAzure OpenAI 大语言模型（LLM）端点URL
  • AZURE_OPENAI_DEPLOYMENT_NAMEAzure OpenAI LLM 部署名称
  • AZURE_OPENAI_API_VERSIONAzure OpenAI LLM API 版本
  • AZURE_OPENAI_EMBEDDING_API_KEYAzure OpenAI Embedding 部署密钥（如果与 OPENAI_API_KEY)
  • AZURE_OPENAI_EMBEDDING_ENDPOINTAzure OpenAI 嵌入服务终端节点URL
  • AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAMEAzure OpenAI 嵌入部署名称
  • AZURE_OPENAI_EMBEDDING_API_VERSIONAzure OpenAI API 版本
  • AZURE_OPENAI_USE_MANAGED_IDENTITY使用 Azure 管理的标识进行身份验证
  • LLM_MAX_TOKENSLLM响应的最大令牌数（默认： 8192)

一般配置

你可以在一个（配置文件/环境中）设置这些变量 .env 项目目录中的文件。一个示例配置文件（sample_env.txt提供了所有可用选项及其默认值。

运行服务器

直接使用以下方式运行Graphiti MCP服务器 uv:

uv run src/graphiti_mcp_server.py

带有选项：

uv run src/graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

可用参数：

  • --model覆盖（或重写） MODEL_NAME 环境变量（仅在不使用 Ollama 时）。
  • --small-model覆盖（或重写） SMALL_MODEL_NAME 环境变量（仅在不使用 Ollama 时）。
  • --temperature覆盖（或重写） LLM_TEMPERATURE 环境变量。
  • --max-tokens覆盖（或重写） LLM_MAX_TOKENS 环境变量。
  • --transport选择传输方法（sse 或 stdio，默认：sse）
  • --port用于绑定MCP服务器的端口（默认：8020）
  • --group-id为图表设置一个命名空间（可选）。如果未提供，则默认为“default”。
  • --destroy-graph如果设置此选项，则在启动时销毁所有Graphiti图表。
  • --use-custom-entities使用预定义的ENTITY_TYPES启用实体提取

Ollama 配置参数

  • --use-ollama使用 Ollama 作为大型语言模型（LLM）和嵌入模型（默认：true）
  • --ollama-base-urlOllama 基础 URL（默认：http://localhost:11434/v1）
  • --ollama-llm-modelOllama LLM 模型名称（默认：deepseek-r1:7b）
  • --ollama-embedding-modelOllama 嵌入模型名称（默认：nomic-embed-text）
  • --ollama-embedding-dimOllama 嵌入维度（默认：768）

Ollama 配置示例

Graphiti MCP服务器为Ollama模型提供了灵活的配置选项。以下是一些常见用例：

基本配置示例

使用默认模型：

# With default .env configuration
uv run src/graphiti_mcp_server.py

# Or explicitly set in .env file:
# USE_OLLAMA=true
# OLLAMA_LLM_MODEL=deepseek-r1:7b
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text

使用不同的大型语言模型（LLM）：

uv run src/graphiti_mcp_server.py --ollama-llm-model llama3.2:3b

使用自定义维度的不同嵌入模型：

uv run src/graphiti_mcp_server.py --ollama-embedding-model all-minilm-l6-v2 --ollama-embedding-dim 384

使用自定义的最大令牌数以获取更长的回复：

uv run src/graphiti_mcp_server.py --max-tokens 32768

连接到远程Ollama服务器：

uv run src/graphiti_mcp_server.py --ollama-base-url http://remote-server:11434/v1 --ollama-llm-model llama3.2:8b

环境变量配置

你也可以使用环境变量来配置Ollama模型 .env 文件：

# Create or edit .env file
nano .env

将以下变量添加到您的（程序/代码/系统等）中 .env 文件：

# Ollama Configuration
OLLAMA_LLM_MODEL=mistral:7b
OLLAMA_EMBEDDING_MODEL=all-minilm-l6-v2
OLLAMA_EMBEDDING_DIM=384
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=32768

然后运行服务器：

uv run src/graphiti_mcp_server.py

配置优先级

配置系统遵循以下优先级顺序（从高到低）：

  1. 命令行界面（CLI）参数 - 覆盖所有其他设置
  2. 环境变量 - 提供默认值，这些值可以通过命令行界面（CLI）进行覆盖
  3. 默认值 - 所有设置的内置默认值

可用的Ollama模型

常见的大型语言模型（LLM）：

  • deepseek-r1:7b （默认）- 性能与质量的良好平衡
  • llama3.2:3b - 用于开发的快速、小型模型
  • llama3.2:8b - 更高质量，更大模型
  • mistral:7b - 在多项任务中表现出色
  • codellama:7b - 专门用于代码生成
  • phi3:3.8b - 微软的高效模型

常见的嵌入模型：

  • nomic-embed-text (默认) - 高质量嵌入
  • nomic-embed-text-v2 - 默认版本的改进版
  • all-minilm-l6-v2 - 快速、高效的嵌入
  • all-MiniLM-L6-v2 - 同一型号的另一种拼写方式
  • text-embedding-ada-002 - 兼容OpenAI的嵌入表示

性能考量

  • 较小的模型 （3B参数）速度更快，但质量可能较低
  • 更大的型号 （7B+参数）提供更高质量，但需要更多资源
  • 嵌入维度 影响性能和存储需求
  • 远程Ollama服务器 可用于分布式部署

并发与大型语言模型（LLM）提供商的429速率限制错误

Graphiti的摄入管道设计为高并发，由（某个系统或组件）控制 SEMAPHORE_LIMIT 环境变量。 默认情况下， SEMAPHORE_LIMIT 被设定为 10 并发操作以帮助防止 429 来自您大型语言模型（LLM）提供商的速率限制错误。如果您遇到此类错误，请尝试降低此值。

如果你的大语言模型（LLM）提供商允许更高的吞吐量，你可以增加 SEMAPHORE_LIMIT 以提高剧集数据摄入性能。

Docker 部署

Graphiti MCP服务器可以使用Docker进行部署。Dockerfile中使用了 uv 对于包管理，确保 一致的依赖项安装。

环境配置

在运行 Docker Compose 设置之前，您需要配置环境变量。您有两个选项：

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

  2. 直接使用环境变量：

    • 你也可以在运行 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 运行

Graphiti MCP 容器可从以下位置获取： zepai/knowledge-graph-mcp以下 Compose 配置使用的是此容器的最新构建版本。

使用 Docker Compose 启动服务：

docker compose up

或者，如果你使用的是较旧版本的 Docker Compose：

docker-compose up

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

  • 用途 uv 用于包管理和运行服务器
  • 从（指定位置）安装依赖项 pyproject.toml 文件
  • 使用环境变量连接到 Neo4j 容器
  • 在端口8020上暴露服务器以支持基于HTTP的SSE传输
  • 包含对Neo4j的健康检查，以确保在启动MCP服务器之前它已完全正常运行

与MCP客户端集成

配置

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

[！重要] 你需要使用Python包管理器， uv 已安装。请参阅 uv 安装说明。

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

使用Ollama（默认）

Ollama的基本配置：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>/dev/graphiti-memory",
        "--project",
        ".",
        "src/graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password"
      }
    }
  }
}

通过CLI参数自定义Ollama模型：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>/dev/graphiti-memory",
        "--project",
        ".",
        "src/graphiti_mcp_server.py",
        "--transport",
        "stdio",
        "--ollama-llm-model",
        "llama3.2:3b",
        "--ollama-embedding-model",
        "all-minilm-l6-v2",
        "--ollama-embedding-dim",
        "384"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password"
      }
    }
  }
}

通过环境变量自定义Ollama模型：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>/dev/graphiti-memory",
        "--project",
        ".",
        "src/graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OLLAMA_LLM_MODEL": "mistral:7b",
        "OLLAMA_EMBEDDING_MODEL": "nomic-embed-text-v2",
        "OLLAMA_EMBEDDING_DIM": "768",
        "LLM_TEMPERATURE": "0.1",
        "LLM_MAX_TOKENS": "32768"
      }
    }
  }
}

使用OpenAI（备选方案）

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>/dev/graphiti-memory",
        "--project",
        ".",
        "src/graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "USE_OLLAMA": "false",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

对于SSE传输（基于HTTP），您可以使用以下配置：

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "sse",
      "url": "http://localhost:8020/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服务器可以通过（某种方式，原文中未明确说明具体方式，但通常可理解为“接口”或“方法”）处理结构化的JSON数据 add_episode 带有工具的 source="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服务器：
python src/graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

提示：指定一个 group_id 为图数据指定命名空间。如果您未指定 group_id服务器将使用“default”作为组ID。

或者

docker compose up
  1. 配置 Cursor 以连接到 Graphiti MCP 服务器。
{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8020/sse"
    }
  }
}

  1. 将Graphiti规则添加到Cursor的用户规则中。参见 `cursor_rules.md` 翻译为中文是：“光标规则.md” 详情见下文。

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

通过集成Graphiti的知识图谱，Cursor中的AI助手能够实现持久记忆功能 能力。

与Claude桌面版（Docker MCP服务器）集成

Graphiti MCP Server 容器使用 SSE MCP 传输协议。Claude Desktop 本身不支持 SSE，因此您需要使用一个网关，如 mcp-remote.

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

    docker compose up

  2. （可选）安装 mcp-remote 在全球范围内: 如果你更倾向于 mcp-remote 全局安装，或者如果你在安装时遇到问题 npx 获取包后，你可以将其全局安装。否则， npx （在下一步中使用）将为您处理。

    npm install -g mcp-remote

  3. 配置Claude桌面版： 打开你的Claude桌面配置文件（通常位于 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:8020/sse" // Ensure this matches your Graphiti server's SSE endpoint
      ]
    }
  }
}

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

  4. 重启Claude桌面版 以便更改生效。

故障排除

Ollama 配置问题

服务器无法与Ollama一起启动：

  • 确保Ollama已安装并正在运行： ollama serve
  • 检查所需模型是否已拉取： ollama list
  • 验证Ollama服务器是否可访问： curl http://localhost:11434/v1/models
  • 检查你的 .env 文件包含 USE_OLLAMA=true （默认）

模型未找到错误：

  • 拉出所需模型： ollama pull <model-name>
  • 检查模型名称的拼写（区分大小写）
  • 验证模型是否存在于Ollama库中

嵌入维度不匹配：

  • 确保 OLLAMA_EMBEDDING_DIM 与你的嵌入模型输出维度相匹配
  • 常见维度：384（all-minilm-l6-v2），768（nomic-embed-text），1536（nomic-embed-text-v2）

性能问题：

  • 尝试使用更小的模型以获得更快的响应时间
  • 调整 SEMAPHORE_LIMIT 用于并发控制
  • 考虑使用远程Ollama服务器来处理分布式工作负载

一般问题

Neo4j连接错误：

  • 验证Neo4j是否正在运行且可访问
  • 检查连接凭据和URI
  • 确保Neo4j版本为5.26或更高版本

MCP客户端连接问题：

  • 验证传输方法（stdio 与 sse）是否符合客户端要求
  • 检查SSE传输的端口配置
  • 确保防火墙允许在配置端口上建立连接

要求

  • Python 3.10 或更高版本
  • Neo4j 数据库（需版本5.26或更高）
  • Ollama（注：这是一个专有名词，通常指一个特定的软件或项目名称，在中文中直接保留原样） 已安装并运行（默认）或OpenAI API密钥（用于LLM操作）
  • 与MCP兼容的客户端

遥测

Graphiti MCP服务器使用了Graphiti核心库，该库包含匿名遥测数据收集功能。在初始化Graphiti MCP服务器时，会收集匿名使用统计数据，以帮助改进该框架。

收集的内容

  • 匿名标识符和系统信息（操作系统、Python版本）
  • Graphiti版本及配置选项（LLM提供商、数据库后端、嵌入器类型）
  • 从未收集过任何个人数据、API密钥或实际的图表内容

如何禁用

要在MCP服务器中禁用遥测功能，请设置环境变量：

export GRAPHITI_TELEMETRY_ENABLED=false

或者将其添加到您的 .env 文件：

GRAPHITI_TELEMETRY_ENABLED=false

关于收集了哪些信息以及收集原因的完整详情，请参阅 主Graphiti README文件中的遥测部分.

📦 分发与出版

这个项目通过GitHub Actions和可信发布功能自动发布到PyPI：

  • **PyPI（Python Package Index）**https://pypi.org/project/montesmakes.graphiti-memory/ 翻译为中文是：https://pypi.org/项目/montesmakes.graphiti-memory/（注：实际网址翻译中，网址本身通常不直接翻译，但为了符合中文表达习惯，这里保留了网址的结构说明，实际使用时直接使用原网址即可）
  • 安装： uvx montesmakes.graphiti-memory 或者 uv tool install montesmakes.graphiti-memory

对于维护者

当在GitHub上创建新的发布版本时，会自动将其发布到PyPI。向（相关仓库）推送时，会自动进行TestPyPI的部署 main 分支。

🤝 贡献

欢迎投稿！详情请见 `CONTRIBUTING.md` 翻译成中文是“贡献指南.md”或“贡献规范.md”。这个文件通常用于说明如何向某个项目或组织做出贡献，包括贡献的流程、规范、要求等信息 作为指南。

开发环境设置

  1. 克隆仓库：

    git clone https://github.com/mandelbro/graphiti-memory.git
cd graphiti/mcp_server

  2. 安装依赖项：

    uv sync --extra dev

  3. 运行测试：

    uv run pytest

  4. 格式化和代码检查:

    uv run ruff format
uv run ruff check

许可证

此项目采用与父级Graphiti项目相同的许可协议。

相关 MCP