# Gemini CLI

settings.json에 bearer 자격 증명을 넣지 않고 OAuth 우선 Gemini CLI 구성을 사용합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/mcp/gemini
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 0a6aa86e8077d8de0a7e7252c8c9f50fdcc1bda86fd0811f01ffd845f1fd82b8
- Edition-Digest: c70406804140e4f1c85a64a6ae29437cd91c85b2e498d58f5f670d65cd7f38f6
- 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 (호스팅된 엔드포인트용 httpUrl).
- 확장 저장소: github:yonro/xmemo-gemini-cli (매니페스트 0.1.0, 문서화된 GitHub 설치, 공식 갤러리 승인 추론 없음).

## 설치 / 설정

Gemini CLI extensions 명령을 사용하여 확장을 설치하거나, mcpServers 아래의 ~/.gemini/settings.json 에 XMemo 구성 블록을 수동으로 병합하세요.

- 확장 명령: gemini extensions install https://github.com/yonro/xmemo-gemini-cli (yonro/xmemo-gemini-cli @ 39e25b185b README 기준).
- 수동 대체 방법: httpUrl 및 ID 헤더를 보존하면서 XMemo 블록을 ~/.gemini/settings.json 에 병합합니다.

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

## 자격 증명 설정

키 없음 — Gemini CLI를 재시작한 후 브라우저 OAuth를 완료합니다. settings.json에 XMEMO_KEY 또는 Authorization header를 넣지 않습니다.

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

## XMEMO_AGENT_INSTANCE_ID 생성 / 확인

Gemini CLI 로컬 설치마다 secret이 아닌 값을 하나 생성하고 git 밖에 저장한 뒤 재시작 후에도 재사용하여 attribution을 안정적으로 유지합니다.

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

## 기존 구성 블록 유지

이 페이지에 렌더링된 기존 Gemini CLI XMemo 구성 블록을 사용합니다. httpUrl과 비밀이 아닌 identity header를 유지하고 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를 재시작하여 엔드포인트와 현재 instance identity를 불러온 다음 OAuth consent를 완료합니다.

## 실제 recall 호출로 테스트

첫 MCP 호출은 읽기 전용으로 수행합니다. 이는 health-check placeholder가 아닌 실제 recall 호출이며 memory를 쓰지 않습니다.

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

## 예상 응답 (리터럴 형태)

성공한 호출은 아래의 공개 ranked text 형태를 반환합니다. reference와 content는 승인된 memory space의 실제 값입니다.

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

## 일반적인 오류

Gemini CLI의 OAuth 실패는 호스팅 OAuth 오류 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}"
      }
    }
  }
}
```