# Gemini CLI

使用 OAuth-first 的 Gemini CLI 配置，不要将 bearer credentials 放入 settings.json。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/gemini
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 0a6aa86e8077d8de0a7e7252c8c9f50fdcc1bda86fd0811f01ffd845f1fd82b8
- Edition-Digest: 7dae5c3afa36bb259288eb367d17667898456f5327c0cdd6c697eaa58c8b7475
- Source-Revision: sha256:5d9fac621d4eb098b31be9ae2758612bab42ce262e90628f5866b3d7ef7f90b9

## 前置条件

使用具备经审查的 settings.json MCP 配置和浏览器 OAuth 支持的 Gemini CLI 开发者工具。支持仅适用于 Gemini CLI 开发者工具，并不意味着集成了 Gemini 消费者网页聊天 (gemini.google.com) 或获得了官方扩展商店批准。

- 端点：https://xmemo.dev/mcp.
- 认证模式: OAuth.
- 配置文件: ~/.gemini/settings.json.
- 传输协议: Streamable HTTP (托管 endpoint 使用 httpUrl)。
- 扩展仓库: github:yonro/xmemo-gemini-cli (清单 0.1.0；已记录 GitHub 安装，未推断官方扩展商店批准)。

## 安装 / 设置

使用 Gemini CLI extensions 命令安装扩展，或者手动将 XMemo 配置块合并到 ~/.gemini/settings.json 的 mcpServers 下。

- 扩展命令: gemini extensions install https://github.com/yonro/xmemo-gemini-cli (锚定至 yonro/xmemo-gemini-cli @ 39e25b185b README)。
- 手动后备方案: 将 XMemo 块合并到 ~/.gemini/settings.json，保留 httpUrl 和身份头。

```bash
gemini extensions install https://github.com/yonro/xmemo-gemini-cli
```

## 设置凭据

无需 key——重启 Gemini CLI 后完成浏览器 OAuth。不要将 XMEMO_KEY 或 Authorization header 放入 settings.json。

```text
No XMEMO_KEY
Complete browser OAuth in Gemini CLI
```

## 生成 / 确认 XMEMO_AGENT_INSTANCE_ID

每个本地 Gemini CLI install 生成一个非机密值，将它保存在 git 外，并在重启后复用，使 attribution 保持稳定。

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
```

## 保留现有 config block

使用本页面渲染的现有 Gemini CLI XMemo configuration block。保留 httpUrl 和非机密 identity headers；不要添加 Authorization 或 XMEMO_KEY。

```json
{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## 重启客户端

保存 settings.json 后重启 Gemini CLI，使其加载 endpoint 和当前 instance identity，然后完成 OAuth consent。

## 使用真实 recall call 测试

第一次 MCP call 应为只读。这是实际的 recall invocation，不是 health-check placeholder，也不会写入 memory。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（literal shape）

成功调用会返回下面的公开 ranked text shape；reference 和 content 是来自已授权 memory space 的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 常见错误

Gemini CLI OAuth failures 使用 hosted OAuth error contract。

- invalid_grant — OAuth authorization code 无效、已过期或已被使用：重新连接 Gemini CLI 并再次授权。
- invalid_target — OAuth resource 与此 MCP server 不匹配：使用 https://xmemo.dev/mcp 并重新连接。
- 403 insufficient_scope — grant 不包含 memory:read：批准请求的 scope 并重新连接。

## Gemini CLI

OAuth client: merge this XMemo block into settings.json, set one stable XMEMO_AGENT_INSTANCE_ID for local attribution, then restart Gemini CLI and complete MCP OAuth. Do not add Authorization or XMEMO_KEY to this snippet.

```
{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```