1. 场景与目标

在日常的开发工作流中，我们常常希望将强大的语言模型（如 Gemini）与外部工具集（如记忆、检索、知识图谱）相结合，以打造更智能、更自动化的助手。本文的核心目标就是将 Gemini CLI 与 Graphiti MCP (Memory, Control, Perception) 服务进行对接，让 Gemini CLI 能够直接调用 Graphiti 提供的丰富工具。

为此，我们主要探讨两种连接思路：

1. 本地 stdio 方式：Gemini CLI 在启动时，会自动 fork 一个 Graphiti 子进程，并通过标准输入/输出（stdin/stdout）进行高效的本地通信。这种方式配置简单，无需网络设置。
2. 远端 HTTP/SSE 方式：Graphiti 作为一个常驻服务（通过 Docker 或源码 uv run 启动），Gemini CLI 则通过 Server-Sent Events (SSE) 长连接来访问它。这种方式更适合分布式或服务化的部署场景。

2. 前置准备

在开始配置之前，请确保完成以下准备工作：

1. 安装 Gemini CLI：

   # 通过 Homebrew (macOS)
   brew install gemini
   # 或通过 npm
   npm install -g @gemini-cli/core

2. 获取并启动 Graphiti MCP Server： 您可以选择以下任一方式启动 Graphiti 服务。

   • Docker (推荐)：

     # 在 Graphiti 项目根目录
     docker-compose up -d

   • 源码启动：

     # 确保已安装 uv
     uv run graphiti_mcp_server.py --transport sse --model gpt-4o

3. 配置环境变量： Graphiti 需要访问 OpenAI API 和 Neo4j 数据库，请确保以下环境变量已正确设置：

   export OPENAI_API_KEY="sk-..."
   export NEO4J_PASSWORD="your-neo4j-password"

4. 确认服务端口： 启动后，Graphiti 默认在 localhost:8000 暴露服务。您可以通过访问以下端点来确认服务是否正常运行：

   • SSE 端点: http://localhost:8000/sse
   • WebSocket 端点: http://localhost:8000/ws

3. 配置方法 A：Gemini CLI 本地启动 Graphiti (stdio)

这种方法让 Gemini CLI 托管 Graphiti 进程，适合快速本地集成。

打开 Gemini CLI 的配置文件 ~/.gemini/settings.json，并添加以下 mcpServers 配置：

{
  "mcpServers": {
    "graphiti": {
      "command": "uv",
      "args": ["run", "graphiti_mcp_server.py", "--model", "gpt-4o", "--transport", "stdio"],
      "cwd": "/ABSOLUTE/PATH/TO/graphiti-mcp-server",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "NEO4J_PASSWORD": "..."
      },
      "trust": true
    }
  }
}

• command & args: 定义了启动 Graphiti 服务的命令。
• cwd: 必须填写 Graphiti MCP Server 项目的绝对路径。
• env: 用于传递必要的环境变量。
• 优点: 配置简单，零端口冲突，无需额外网络设置。

配置完成后，重新打开一个新的 gemini 终端。输入 /mcp 命令，如果看到 graphiti 服务已连接，则表示配置成功。

4. 配置方法 B：Gemini CLI 连接常驻 Graphiti 服务 (SSE)

如果 Graphiti 已经作为一个独立服务在运行，可以使用此方法连接。

同样，在 ~/.gemini/settings.json 中添加配置：

{
  "mcpServers": {
    "graphiti": {
      "url": "http://127.0.0.1:8000/sse",
      "timeout": 8000,
      "trust": true
    }
  }
}

• url: 这是关键字段。请确保使用 url 而不是 httpUrl，这会告诉 Gemini CLI 使用 GET 方法和 text/event-stream 类型进行连接，以兼容 SSE。
• timeout: 建议设置一个较长的超时时间（如 8000ms），以适应可能存在的网络延迟。
• headers: 如果您的远程服务需要认证，可以在此添加 Authorization 头，例如："headers": { "Authorization": "Bearer your-token" }。

验证连接:

1. 测试 SSE 流:

   curl -N http://127.0.0.1:8000/sse | head

   如果能看到持续输出的心跳事件（如 event: ping），说明 SSE 服务正常。

2. 在 Gemini CLI 中检查: 启动 gemini，然后运行 /mcp desc graphiti。如果成功列出了 Graphiti 提供的工具列表，则连接成功。

5. 常见错误 & 解决方案

6. 快速排查脚本

当遇到问题时，以下命令可以帮助您快速定位：

1. 检查 Graphiti 进程和端口占用:

   # 查看哪个进程在使用 8000 端口
   lsof -Pni :8000

2. 测试 SSE 连通性:

   # 持续监听 SSE 事件流
   curl -N http://127.0.0.1:8000/sse | head

3. 开启 Gemini CLI 调试模式:

   # 启动时附加 --debug 参数，查看详细日志
   gemini --debug

7. 一句话总结

整个对接过程的核心可以概括为：启动 Graphiti 服务 → 在 ~/.gemini/settings.json 中正确填写 url 或 command → 重启 Gemini CLI。完成这三步，您就可以在终端中无缝使用 Graphiti 提供的强大工具集了。