gemini-web-mcp

MCP server for querying Gemini Web (https://gemini.google.com/app) from Claude Code / other MCP clients. Uses HanaokaYuzu/Gemini-API (gemini-webapi) under the hood with cookie-based auth.

設計詳細は docs/design.md を参照。

Tested on

Linux, macOS. Windows is unsupported (パスは ~/.config/... 決め打ち、fcntl 依存)。

Related MCP server: MCP Server Gemini

Install (Claude Code に登録)

private repo なので host 側で github.com に SSH key を登録済みであること前提。

claude mcp add gemini-web -- \
  uvx --from git+ssh://git@github.com/TakashiAihara/gemini-web-mcp.git \
  gemini-web-mcp serve

browser-cookie3 で自動 cookie 抽出を使う場合は [browser] extra:

claude mcp add gemini-web -- \
  uvx --from "git+ssh://git@github.com/TakashiAihara/gemini-web-mcp.git[browser]" \
  gemini-web-mcp serve

cookie を env 直接渡し or default model を上書き:

claude mcp add gemini-web \
  --env GEMINI_WEB_MCP_DEFAULT_MODEL='3.6 Flash' \
  --env GEMINI__SECURE_1PSID=... \
  --env GEMINI__SECURE_1PSIDTS=... \
  -- uvx --from git+ssh://git@github.com/TakashiAihara/gemini-web-mcp.git gemini-web-mcp serve

SSH key が使えない環境 (CI 等) では git+https://... + gh auth setup-git 済みの credential helper で fallback。

認証 (初回)

cookie cache を作っておくと、以降の serve 起動時に再 login 不要です (__Secure-1PSIDTS は gemini-webapi が自動 refresh します)。

A. server とブラウザが同じホストにある場合

browser-cookie3 がローカルの Chrome / Firefox 等から自動抽出します。

uvx --from "git+ssh://git@github.com/TakashiAihara/gemini-web-mcp.git[browser]" \
  gemini-web-mcp login

B. server がリモートホストにある場合

MCP server は Claude Code が起動するため Claude Code と同じホストで動きます。手元の PC でブラウザを使い、Claude Code をリモートの Linux で動かしている構成では、リモート側に Google のセッションを持つブラウザが無いので A は使えません。cookie を env で渡します。

1. ブラウザで https://gemini.google.com を開く

2. DevTools > Application > Cookies > https://gemini.google.com から __Secure-1PSID と __Secure-1PSIDTS を取得

3. リモート側で即座に実行 (__Secure-1PSIDTS は短時間で失効します)

GEMINI__SECURE_1PSID='...' GEMINI__SECURE_1PSIDTS='...' \
  uvx --from git+https://github.com/TakashiAihara/gemini-web-mcp.git \
  gemini-web-mcp login

一度成功すれば ~/.config/gemini-web-mcp/cookies/ にキャッシュされ、以降は自動で更新されるため env は不要になります。claude mcp add 側にも cookie を書く必要はありません。

コマンドを PATH に置く (任意)

claude mcp add で登録しただけでは gemini-web-mcp は PATH に入りません (MCP 起動時に uvx がその場で解決するため)。login を何度も叩くなら入れておくと楽です。

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

cookie は Google アカウントのセッションそのものです。チャットや issue に貼らず、shell 履歴に残したくない場合は secret manager 経由で注入してください。

期限切れ時

AUTH_EXPIRED が返ったら login をやり直します。失敗時は渡し方の案内が表示されます。

提供する MCP tool

gemini_chat_new は thinking=true で強化思考モードになります (下記)。

label は [a-zA-Z0-9_\-]{1,64} の文字列。会話継続に必要な metadata は server 側が label に紐づけて保持するので、呼び出し側は ID を覚えなくてよい。

手動セッションとの分離

既定で temporary モードを使うため、MCP 由来の会話は Gemini Web のサイドバー履歴に出ません。手元で手動利用している会話履歴に MCP の会話が混ざらないようにするためです。履歴に残したい場合は GEMINI_WEB_MCP_TEMPORARY=0 を設定します。

履歴に出ないにもかかわらず、label に紐づけた metadata を server 側が保持しているため 別プロセス・別セッションからでも会話を継続できます (実測確認済み、docs/design.md §13.7)。

モデル

gemini_models_list() でアカウントに紐づくモデルを取得できます (2026-08-02 時点の実測例):

gemini_chat_new(model=...) には UI 表記 ("3.6 Flash") / display 名 ("Pro") / model_id / 旧ライブラリ名 ("gemini-3-pro") のいずれでも渡せます。既定は "Pro"。版番号ではなく display 名を既定にしているのは、Google が Pro / Flash / Flash-Lite という区分を保ったまま版を上げる (3.1 Pro → 3.2 Pro) ためです。

強化思考モード

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

内部的にはモデルヘッダー配列の index 15 に 2 を入れています (1 = 通常 / 2 = 拡張)。実ブラウザの capture 差分と MCP 経由の UI 表示の両方で確認済みです。

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

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

設定

sessions.json (label → 会話 metadata の永続化) は ~/.config/gemini-web-mcp/sessions.json。permissions は dir 0700 / file 0600。

開発

uv sync --all-extras
uv run pytest -v

依存の pin について

gemini-webapi は PyPI 版ではなく git master を rev pin しています。PyPI 最新リリース v2.0.0 (2026-04-06) は ChatSession が DEFAULT_METADATA を複製せず全 session で共有するバグを含み、別 label の会話に前の会話の cid が漏れます。修正は 2026-04-08 の commit にありますが、以降リリースが切られていません。詳細と解除条件は pyproject.toml の [tool.uv.sources] コメントを参照。

License

AGPL-3.0-or-later. See LICENSE.

依存する gemini-webapi が AGPL-3.0 のため、本パッケージもそれに揃えています。