如何将 Graphiti MCP 服务器以 stdio 方式接入 Claude Desktop？

如何将 Graphiti MCP 服务器以 stdio 方式接入 Claude Desktop？

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti

Claude Desktop 只支持 stdio 传输，而 Graphiti MCP 服务器默认使用 HTTP 传输（http://localhost:8000/mcp/），无法直接填一个 URL 连进去。本文的目标是把仓库mcp_server/目录下的 Graphiti MCP 服务器作为本地进程启动，通过uv run main.py --transport stdio的方式接入 Claude Desktop，使其能够调用 Graphiti 的知识图谱工具（add_memory、search_nodes、get_status等）。适用前提：机器上已安装 Python 3.10+（独立运行 MCP 服务器时需要）、uv，有一个可用的 LLM API Key（如 OpenAI），以及一个图数据库（默认 FalkorDB，或 Neo4j 5.26 及以上）。

准备环境

按 mcp_server/README.md 的 Quick Start 与 Setup 小节，stdio 客户端需要三步准备：

1. 克隆仓库并记下mcp_server所在目录的完整路径：

git clone https://github.com/getzep/graphiti.git cd graphiti && pwd

2. 安装uv（如未安装）并在mcp_server目录创建虚拟环境、安装依赖：

# 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

uv sync需要在graphiti/mcp_server目录下执行。如果之后还要用 Anthropic、Gemini 等 LLM 或 Voyage 等嵌入服务，再执行带--extra providers的安装。

3. 准备好 API Key 和图数据库：

• LLM：默认配置使用 OpenAI（模型gpt-5.5），需要准备OPENAI_API_KEY；也可以换用anthropic、gemini、groq、azure_openai等 provider。
• 数据库：README 中 CLI 参数说明--database-provider的默认值是falkordb（连接redis://localhost:6379）。要改用本地已有的 Neo4j，则按 README「Direct Execution with Existing Neo4j」一节准备 Neo4j 并设置NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD环境变量。

配置 Claude Desktop 的 stdio 接入

仓库提供了现成的 stdio 接入配置示例 mcp_server/config/mcp_config_stdio_example.json，核心内容如下：

{ "mcpServers": { "graphiti": { "transport": "stdio", "command": "uv", "args": [ "run", "/ABSOLUTE/PATH/TO/main.py", "--transport", "stdio" ], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USER": "neo4j", "NEO4J_PASSWORD": "demodemo", "OPENAI_API_KEY": "${OPENAI_API_KEY}", "MODEL_NAME": "gpt-5.5" } } } }

按 README「For Claude Desktop and otherstdioonly clients」与「Integrating with MCP Clients」两节的说明，把它写进 Claude Desktop 的配置文件（README 称该文件通常为claude_desktop_config.json；若已有mcpServers条目，把graphiti作为新 key 加进去）。两处占位符需要替换为你机器上的真实值：

• /ABSOLUTE/PATH/TO/main.py：替换为仓库中mcp_server/main.py的绝对路径，即上面pwd得到的graphiti目录下再进入mcp_server/main.py。README 特别强调：「Ensure that you set the full path to theuvbinary and your Graphiti project folder」，所以command建议写成uv的完整路径（README 示例为/Users/<user>/.local/bin/uv，请替换成你机器上uv的实际路径，例如用which uv查询）。
• ${OPENAI_API_KEY}：替换为你的 OpenAI API Key 字面值。

env中的NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD是官方示例给出的 Neo4j 连接值（bolt://localhost:7687、neo4j、demodemo为示例默认值），如果你的 Neo4j 密码不同，请一并修改；MODEL_NAME: "gpt-5.5"对应默认配置 mcp_server/config/config.yaml 中的llm.model，可换成你的模型名。

两点边界说明：

• 上述 env 指向 Neo4j，而服务器默认 provider 是 FalkorDB。如果你的后端确实是 Neo4j，参照 README 的直接执行方式，在args中追加--database-provider、neo4j（该参数在 README「Available Command-Line Arguments」中有列出，默认值为falkordb）；如果就用默认 FalkorDB，则保证本地redis://localhost:6379可达即可。
• README 的「Other MCP Clients」小节还给出了另一种等价写法，在args中使用run --isolated --directory <mcp_server 目录> --project . main.py --transport stdio，适用于不想写main.py绝对路径的场景。

配置完成后重启 Claude Desktop，README 明确说明需要重启才会生效。

验证接入是否成功

方式一：通过get_status工具验证（推荐）。在 Claude Desktop 中让助手调用get_status工具。该工具的定义（见 src 入口）会执行一次数据库查询并返回：

• 成功时返回status='ok'，消息形如Graphiti MCP server is running and connected to <provider> database（provider 为falkordb或neo4j）；
• 服务未初始化时返回status='error'，消息为Graphiti service not initialized；
• 数据库不通时返回status='error'，消息为Graphiti MCP server is running but database connection failed: <错误信息>。

看到ok即说明 stdio 进程、LLM 配置与数据库连接都已打通。

方式二：运行仓库自带的 stdio 测试脚本（可选）。mcp_server/tests/test_stdio_simple.py 就是一个用 MCP SDK 的stdio_client以 stdio 方式拉起服务器的完整客户端：它启动uv run ../main.py --transport stdio，初始化会话、列出工具、调用add_memory（group_id为test_group）和search_memory_nodes。该脚本依赖当前环境变量中的NEO4J_URI/NEO4J_USER/NEO4J_PASSWORD/OPENAI_API_KEY（有默认值，Neo4j 密码默认为graphiti），因此需要先有一个可用的 Neo4j 实例。全部通过时脚本打印✅ All tests completed successfully!（此为脚本自身的输出文本），失败则打印❌ Test failed: <异常信息>并退出码为 1。

已知限制与排查

• Claude Desktop 不支持 HTTP 传输：README 指出「Claude Desktop does not natively support HTTP transport」。所以即使你用docker compose up跑好了默认 HTTP 服务器，也不能把http://localhost:8000/mcp/直接填给 Claude Desktop，必须走本文的 stdio 本地进程方式（HTTP 端点适合 Cursor、VS Code 等支持 HTTP 的客户端）。
• 429 限流：每个 episode 的入库会触发多次 LLM 调用，并发由环境变量SEMAPHORE_LIMIT控制，默认10（README 称适合 OpenAI Tier 3、中档 Anthropic 配额）。若 Claude Desktop 里添加记忆时出现 429 限流错误，按 README 的 provider 分档建议调低该值（例如 OpenAI Tier 1 设为 1–2，Anthropic 默认档设为 5–8），写进mcp_server目录的.env文件。
• 遥测：MCP 服务器初始化时会上报匿名使用统计（不含个人数据、API Key 或图内容）。不需要时设置GRAPHITI_TELEMETRY_ENABLED=false，可写入.env。
• 数据库连接失败的自查：README 测试文档给出了两个检查命令——Neo4j 用curl http://localhost:7474确认服务在线，FalkorDB 用redis-cli ping。若get_status返回database connection failed，先确认对应数据库进程确实在运行、env里的 URI/账号与之一致。

完成以上步骤后，Claude Desktop 会话中的 Graphiti 服务器就处于可用状态：get_status返回ok是接入成功的直接判据；日常使用时即可让 Claude Desktop 调用add_memory写入对话或文档、用search_nodes/search_memory_facts查询知识图谱。

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti