# gemini-web-mcp

Query **Gemini Web** (gemini.google.com) from Claude Code and other MCP clients.

Uses browser cookies instead of the official Gemini API, so an existing Google AI subscription's models and quota can be used. Built on [HanaokaYuzu/Gemini-API](https://github.com/HanaokaYuzu/Gemini-API).

- 会話は自分で決めた `label` で扱えます。conversation ID を持ち回る必要はありません
- 既定では **Gemini Web の履歴に残りません**。手元で使っている会話一覧が MCP の会話で埋まりません
- モデルを選べます (`3.6 Flash` / `Pro` など)。強化思考モードも指定できます

Tested on Linux and macOS. **Windows は未対応** (パスは `~/.config/...` 固定、`fcntl` に依存)。

---

## セットアップ

新しいホストでゼロから始める場合、この順に進めてください。

### 1. インストール

```bash
uv tool install git+https://github.com/TakashiAihara/gemini-web-mcp
```

`gemini-web-mcp` が PATH に入ります。

<details>
<summary>uv が無い場合</summary>

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
</details>

### 2. cookie を入れる

Gemini Web は API キーではなくブラウザの cookie で認証します。取得方法は環境によって 2 通りあります。

#### 2-a. ブラウザが同じホストにある場合

`browser-cookie3` が Chrome / Firefox 等から自動抽出します。

```bash
uv tool install "git+https://github.com/TakashiAihara/gemini-web-mcp[browser]"
gemini-web-mcp login
```

#### 2-b. ブラウザが別ホストにある場合

**Claude Code をリモートの Linux で動かし、ブラウザは手元の PC** という構成ではこちらです。MCP server は Claude Code と同じホストで動くため、リモート側にログイン済みブラウザが無く、自動抽出は使えません。

1. ブラウザで https://gemini.google.com を開く
2. DevTools → Application → Cookies → `https://gemini.google.com`
3. `__Secure-1PSID` と `__Secure-1PSIDTS` の値をコピー
4. **すぐに** 実行 (`__Secure-1PSIDTS` は短時間で失効します)

**対話入力 (推奨)** — 値がコマンドラインに乗らないので shell 履歴に残りません。

```bash
gemini-web-mcp login --interactive
```

```
__Secure-1PSID  :          # 入力は表示されません
__Secure-1PSIDTS: (空可)
```

<details>
<summary>環境変数で渡す場合</summary>

```bash
GEMINI__SECURE_1PSID='...' GEMINI__SECURE_1PSIDTS='...' gemini-web-mcp login
```

**この形は値が shell 履歴 (`~/.zsh_history` 等) に平文で残ります。** 履歴に残したくない場合は上の対話入力を使うか、secret manager 経由で注入してください。
</details>

成功すると:

```
Login OK.
  cookie cache : ~/.config/gemini-web-mcp/cookies
  sessions     : ~/.config/gemini-web-mcp/sessions.json
```

**一度成功すればキャッシュされ、以降は自動更新されます。** 環境変数の再指定は不要で、次の手順で cookie を渡す必要もありません。

> cookie は Google アカウントのセッションそのものです。チャットや issue に貼らないでください。

### 3. 動作確認

```bash
gemini-web-mcp doctor
```

認証・cookie・使えるモデル・保存済み session をまとめて確認します。問題があれば対処方法を表示します。

```
[OK  ] config dir       ~/.config/gemini-web-mcp (mode 0o700)
[OK  ] cookie cache     ~/.config/gemini-web-mcp/cookies (mode 0o700) / 1 件 / 最終更新 0.1 時間前
[OK  ] environment      上書きなし (既定値を使用)
[OK  ] sessions         ~/.config/gemini-web-mcp/sessions.json (未作成 — 会話を作ると生成されます)
[OK  ] authentication   account_status=1000
[OK  ] models           3 件: 3.5 Flash-Lite, 3.6 Flash, 3.1 Pro
[OK  ] default model    'Pro' -> 3.1 Pro
```

ネットワークに出さずローカルの設定だけ見る場合は `--offline` を付けます。

> `doctor` は cookie の値を出力しませんが、**絶対パス (ユーザー名を含む) と契約中のモデル一覧**が出ます。公開 issue に貼る場合はその 2 点を伏せてください。

### 4. Claude Code に登録

```bash
claude mcp add gemini-web -- gemini-web-mcp serve
```

Claude Code を再起動し、`/mcp` で `gemini-web` が認識されていれば完了です。

<details>
<summary>uv tool install を使わない場合</summary>

```bash
claude mcp add gemini-web -- \
  uvx --from git+https://github.com/TakashiAihara/gemini-web-mcp gemini-web-mcp serve
```

この場合 `gemini-web-mcp` は PATH に入らないため、`login` / `doctor` も `uvx --from ...` 経由で叩く必要があります。
</details>

---

## 使い方

| tool | 用途 |
|---|---|
| `gemini_chat_new(prompt, label, model?, thinking?)` | 新規会話を開始し、`label` で名前を付ける |
| `gemini_chat_continue(label, prompt)` | 既存の会話を再開して続きを訊く |
| `gemini_chat_list()` | 保存中の会話一覧 |
| `gemini_chat_history(label)` | 指定した会話の履歴を全件返す |
| `gemini_chat_delete(label)` | 指定した会話をローカルから削除 |
| `gemini_models_list()` | このアカウントで使えるモデル一覧 |

`label` は `[a-zA-Z0-9_\-]{1,64}`。会話継続に必要な metadata は server が保持するので、呼び出し側は ID を覚える必要がありません。

### 手元の会話との分離

既定で **temporary モード** を使うため、MCP 経由の会話は Gemini Web のサイドバーに出ません。手元で使っている履歴に混ざらないようにするためです。

履歴に残したい場合は `GEMINI_WEB_MCP_TEMPORARY=0` を設定します。

履歴に出ないにもかかわらず、`label` に紐づけた metadata を server が保持しているため **別プロセス・別セッションからでも会話を継続できます**。

### モデル

`gemini_models_list()` でアカウントに紐づくモデルを取得できます (実測例):

| name | display | 説明 |
|---|---|---|
| `3.5 Flash-Lite` | Flash-Lite | すばやく回答を得るのに最適 |
| `3.6 Flash` | Flash | あらゆる場面でサポート |
| `3.1 Pro` | Pro | 高度な数学とコーディングに最適 |

`model` には **UI 表記 (`"3.6 Flash"`) / display 名 (`"Pro"`) / model_id** のいずれでも渡せます。既定は `"Pro"`。版番号ではなく display 名を既定にしているのは、Google が Pro / Flash / Flash-Lite の区分を保ったまま版を上げる (3.1 Pro → 3.2 Pro) ためです。

`gemini_chat_continue` ではモデルを変更できません。Gemini が会話途中のモデル変更を拒否するためで、別モデルで訊きたい場合は `gemini_chat_new` で新しい label を作ってください。

### 強化思考モード

`gemini_chat_new(thinking=True)` で強化思考モード (UI 表記「Flash 拡張」等) を有効にできます。難問向けで、応答は遅くなりますが `thoughts` に思考過程が返ることがあります。会話ごとに固定され `gemini_chat_continue` にも引き継がれます。

なお `thoughts` は同一条件でも返ったり返らなかったりするため、強化思考が効いているかの判定には使えません。

---

## 設定

| env | 既定値 | 用途 |
|---|---|---|
| `GEMINI_WEB_MCP_DEFAULT_MODEL` | `Pro` | `model` 省略時の既定 |
| `GEMINI_WEB_MCP_TEMPORARY` | `1` | `1`=履歴に出さない / `0`=出す |
| `GEMINI_COOKIE_PATH` | `~/.config/gemini-web-mcp/cookies` | cookie キャッシュの場所 |
| `GEMINI__SECURE_1PSID` | (空) | cookie を直接渡す (初回のみ) |
| `GEMINI__SECURE_1PSIDTS` | (空) | 同上 |
| `XDG_CONFIG_HOME` | (空 = `~/.config`) | 設定ディレクトリの基点 |

`sessions.json` は `~/.config/gemini-web-mcp/sessions.json`。ディレクトリは 0700、ファイルは 0600 で作られます。

### 複数アカウントを併用する

`GEMINI_COOKIE_PATH` と `XDG_CONFIG_HOME` を分ければ、アカウントごとに MCP server を並立できます。

```bash
claude mcp add gemini-web-work \
  --env GEMINI_COOKIE_PATH=$HOME/.config/gemini-web-mcp-work/cookies \
  --env XDG_CONFIG_HOME=$HOME/.config/gemini-web-mcp-work-xdg \
  -- gemini-web-mcp serve
```

---

## 困ったとき

まず `gemini-web-mcp doctor` を実行してください。

| 症状 | 対処 |
|---|---|
| `AUTH_EXPIRED` が返る | cookie の期限切れです。`gemini-web-mcp login --interactive` で入れ直してください |
| `command not found: gemini-web-mcp` | `uv tool install` していないか、PATH が通っていません |
| `MODEL_INVALID` が返る | `gemini_models_list()` で使えるモデル名を確認してください |
| `USAGE_LIMIT` が返る | Google AI 側の使用量上限です。リセットまで待つ必要があります |
| Claude Code が tool を認識しない | Claude Code を再起動し、`claude mcp list` に出ているか確認してください |

---

## 開発

```bash
git clone https://github.com/TakashiAihara/gemini-web-mcp
cd gemini-web-mcp
uv sync --all-extras
uv run pytest -v
```

設計と、モデル選択・思考モードの解析経緯は [`docs/design.md`](docs/design.md) にあります。

### 依存の pin について

`gemini-webapi` は PyPI 版ではなく git の特定 commit を pin しています。PyPI 最新リリース v2.0.0 は `ChatSession` が状態を全 session で共有するバグを含み、別の会話に前の会話の ID が漏れます。修正は commit にありますが、以降リリースが切られていません。解除条件は `pyproject.toml` の `[tool.uv.sources]` を参照してください。

---

## License

AGPL-3.0-or-later. See [`LICENSE`](LICENSE).

依存する [gemini-webapi](https://github.com/HanaokaYuzu/Gemini-API) が AGPL-3.0 のため、本パッケージもそれに揃えています。