Skip to main content
Glama

gemini-web-mcp

Modern, lightweight, process-safe MCP (Model Context Protocol) Server that wraps Web Gemini (gemini.google.com) as an on-demand subagent for AI coding assistants (Antigravity, Claude Code, Cursor, Gemini CLI).

现代化、轻量级、跨进程并发安全的 MCP Server,将 Web 端 Gemini(gemini.google.com) 包装为供 AI 编程助手按需调用的“外包 Subagent”。


Features / 核心特性

  • Lean 3-Tool Surface / 精简高信噪比三工具:

    • gemini_ask (openWorldHint=True): Multi-turn text & multimodal Q&A, model/thinking selection, progress heartbeats, and [session | turn | model] status footer.

    • gemini_sessions: Manage persistent named sessions (list / get / delete / clear).

    • gemini_health (readOnlyHint=True): Check auth source, masked proxy, available dynamic models, and connectivity.

  • Multi-Process & Async Safe / 多进程与并发安全:

    • Uses SQLite WAL mode (~/.config/gemini-web-mcp/sessions.db) + per-label asyncio.Lock so multiple IDE windows never clobber each other's sessions, while full metadata lists (3 or 4+ elements) are preserved verbatim.

  • Cross-Model 1050 Guard / 跨模型防 1050 保护:

    • Automatically inherits the session's bound model on follow-ups and blocks accidental mid-session model switching before hitting Google's backend.

  • Multi-Source Auth + Rotation Sync / 多级鉴权与轮换缓存协同:

    • Priority: GEMINI_SECURE_1PSID (+ GEMINI_SECURE_1PSIDTS) -> ~/.config/gemini-web-mcp/cookies.json (dict or Cookie-Editor array) -> optional browser-cookie3, coordinated with gemini-webapi's rotated 1PSIDTS cache.

  • Strict stdio Purity / stdio 零污染:

    • Forces loguru and stdlib logging onto sys.stderr at startup before importing third-party clients so stdout carries pure JSON-RPC frames only.

  • Upload Security Guardrails / 附件上传安全校验:

    • Resolves symlinks and blocks ~/.ssh, ~/.aws, ~/.gnupg, .env* (except .env.example), cookies.json, sessions.db, directories, and oversized files (>20 MB default).

  • Pluggable Backend Architecture / 可插拔后端抽象:

    • Built around GeminiBackend ABC (CookieBackend today, cleanly extensible for future browser-bridge backends).

Related MCP server: gemini-mcp-server

Architecture / 架构概览

flowchart LR
    Client["Antigravity / Claude Code / Cursor"] <-->|"MCP (stdio JSON-RPC only)"| Server["gemini-web-mcp Server"]
    Server -.->|"Logs isolated"| Stderr["sys.stderr"]
    Server --> Backend["GeminiBackend (ABC)"]
    Server --> Store["SessionStore (SQLite WAL)"]
    Server --> Auth["AuthLoader (Rotated Cache -> Env -> cookies.json -> browser-cookie3)"]
    Backend --> Cookie["CookieBackend (gemini-webapi 2.x + Proxy)"]
    Cookie --> Gemini["gemini.google.com"]

For AI Agents: Automated Self-Setup / AI Agent 自动配置指南

User Quick Prompt / 给其他 AI Agent 的一句话指令:

Please read https://github.com/Jefferyu/gemini-web-mcp and follow the "For AI Agents: Automated Self-Setup" instructions in README.md to configure the gemini-web-mcp MCP server and the gemini-web skill for my current environment without overwriting my existing configs.

If you are an AI coding assistant (Antigravity, Claude Code, Cursor, Gemini CLI, Codex, etc.) asked to install and configure this MCP server for the user, follow these steps in order:

Step 1: Ensure uv is installed (Python >= 3.11 managed automatically)

  • Check uv --version.

  • If missing:

    • macOS: brew install uv (or curl -LsSf https://astral.sh/uv/install.sh | sh)

    • Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Choose Installation Mode

  • Mode A (Recommended if installing Skill locally too): Clone the repo to a persistent local folder (e.g. ~/agent/gemini-web-mcp or ~/.local/share/gemini-web-mcp) and sync dependencies:

    git clone https://github.com/Jefferyu/gemini-web-mcp.git ~/gemini-web-mcp
    cd ~/gemini-web-mcp
    uv sync --python 3.12
    # Optional: include --extra browser-cookies if the user wants automatic local browser cookie fallback
    # uv sync --python 3.12 --extra browser-cookies
  • Mode B (Zero-clone via uvx): Run directly from GitHub without cloning:

    uvx --from git+https://github.com/Jefferyu/gemini-web-mcp.git gemini-web-mcp

Step 3: Register MCP Server (Merge Only — NEVER Overwrite Existing Config!)

Read the user's existing MCP configuration file first, preserve all existing mcpServers entries, and merge "gemini-web-mcp" into mcpServers:

  • Antigravity: ~/.gemini/config/mcp_config.json

  • Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

  • Claude Code: claude mcp add ... or ~/.claude.json / .mcp.json

  • Gemini CLI: ~/.gemini/settings.json

Use local clone (command: "uv"):

{
  "mcpServers": {
    "gemini-web-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/gemini-web-mcp",
        "run",
        "gemini-web-mcp"
      ],
      "env": {
        "GEMINI_WEB_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Or zero-clone (command: "uvx"):

{
  "mcpServers": {
    "gemini-web-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Jefferyu/gemini-web-mcp.git",
        "gemini-web-mcp"
      ],
      "env": {
        "GEMINI_WEB_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Proxy Check (macOS GUI Apps): GUI apps do not inherit shell proxy env vars (HTTPS_PROXY / HTTP_PROXY). If the user's network requires a proxy to reach gemini.google.com, detect their local proxy or ask for the proxy URL and add "GEMINI_WEB_MCP_PROXY": "http://127.0.0.1:<port>" inside "env".

Step 4: Install the gemini-web Skill (Progressive Disclosure)

Install examples/skills/gemini-web/SKILL.md (raw URL: https://raw.githubusercontent.com/Jefferyu/gemini-web-mcp/main/examples/skills/gemini-web/SKILL.md) so the assistant knows when and how to invoke gemini_ask without bloating permanent context:

  • Antigravity:

    • Global (all projects): ~/.gemini/config/skills/gemini-web/SKILL.md

    • Project-local: .agents/skills/gemini-web/SKILL.md

  • Claude Code:

    • Global: ~/.claude/skills/gemini-web/SKILL.md

    • Project-local: .claude/skills/gemini-web/SKILL.md

  • Optional Routing Rule: Only if the user wants proactive routing in project rules, merge examples/GEMINI.md into AGENTS.md / GEMINI.md / CLAUDE.md.

  1. Verify stdio JSON-RPC purity by sending an MCP initialize + tools/list payload and confirming gemini_ask, gemini_sessions, and gemini_health are returned cleanly on stdout.

  2. Check credential readiness (either via gemini_health after restart, or running CookieBackend(Settings()).health()).

  3. If health() reports missing cookies or macOS Safari/Keychain permission error:

    • Never ask the user to paste cookies into chat if avoidable; instead instruct them to write ~/.config/gemini-web-mcp/cookies.json directly:

      {
        "__Secure-1PSID": "paste-value-here",
        "__Secure-1PSIDTS": "paste-value-if-present"
      }
    • Or, on macOS with Safari logged in and --extra browser-cookies enabled, instruct them to grant Full Disk Access to the host app (Terminal / Antigravity) if they prefer automatic Safari cookie reading.


Installation & Running / 安装与运行

Requires Python >= 3.11 (managed via uv).

Option 1: From Local Checkout / 本地源码运行

git clone https://github.com/Jefferyu/gemini-web-mcp.git
cd gemini-web-mcp
uv sync --python 3.12 --extra dev
uv run gemini-web-mcp

Option 2: Direct via uvx from GitHub / 直接通过 uvx 运行

uvx --from git+https://github.com/Jefferyu/gemini-web-mcp.git gemini-web-mcp

(Once published to PyPI: uvx gemini-web-mcp)

(Optional) To enable local browser cookie extraction fallback:

uv sync --extra browser-cookies

Best Practice / 最佳实践:

  • Use a dedicated secondary Google account for automation if possible to avoid session eviction from your primary browser.

  • macOS / Chrome 130+ Note: Chrome's App-Bound Encryption and macOS Keychain prompts can block browser-cookie3. Manual export to cookies.json or environment variables is the most reliable setup.

Method A: ~/.config/gemini-web-mcp/cookies.json (Recommended)

  1. Log in to https://gemini.google.com in your browser.

  2. Open DevTools (Application -> Cookies -> https://gemini.google.com) or a cookie exporter extension, and copy __Secure-1PSID and (if present) __Secure-1PSIDTS.

  3. Save either a simple key-value JSON object or a Cookie-Editor JSON array to ~/.config/gemini-web-mcp/cookies.json:

{
  "__Secure-1PSID": "your-1psid-cookie-value",
  "__Secure-1PSIDTS": "your-1psidts-cookie-value"
}

Method B: Environment Variables / 环境变量

export GEMINI_SECURE_1PSID="your-1psid-cookie-value"
export GEMINI_SECURE_1PSIDTS="your-1psidts-cookie-value"

Proxy & Timeout Configuration (macOS GUI Clients!) / 代理与超时配置

Important for macOS GUI apps (Antigravity IDE, Cursor, Claude Desktop): GUI apps launched from Finder/Dock do not inherit shell proxy variables (HTTP_PROXY / HTTPS_PROXY) from ~/.zshrc. Set GEMINI_WEB_MCP_PROXY explicitly in your MCP client's env block if your network requires a proxy to reach gemini.google.com:

"env": {
  "GEMINI_WEB_MCP_PROXY": "http://127.0.0.1:7890",
  "GEMINI_WEB_MCP_LOG_LEVEL": "WARNING"
}

Environment Variables Reference / 环境变量一览

Variable

Default

Description

GEMINI_WEB_MCP_PROXY

Fallback to HTTPS_PROXY / HTTP_PROXY / ALL_PROXY

HTTP/SOCKS proxy URL passed to curl-cffi

GEMINI_WEB_MCP_DEFAULT_MODEL

unspecified

Default model (unspecified, flash, pro, thinking, or exact name)

GEMINI_WEB_MCP_COOKIES_PATH

~/.config/gemini-web-mcp/cookies.json

Path to JSON cookie file

GEMINI_WEB_MCP_SESSIONS_DB_PATH

~/.config/gemini-web-mcp/sessions.db

Path to SQLite WAL session store

GEMINI_WEB_MCP_TIMEOUT_SECONDS

120

Standard request timeout (seconds)

GEMINI_WEB_MCP_THINKING_TIMEOUT_SECONDS

300

Timeout when thinking mode is active

GEMINI_WEB_MCP_MAX_FILES_PER_REQUEST

10

Max attachments per gemini_ask call

GEMINI_WEB_MCP_MAX_FILE_SIZE_MB

20

Max size per attachment (MB)

GEMINI_WEB_MCP_LOG_LEVEL

WARNING

stderr log level (DEBUG/INFO/WARNING/ERROR)

Client Timeout Tip: For model="thinking" or large file uploads, configure your MCP client's tool call timeout >= 300 seconds if supported. gemini-web-mcp emits MCP progress heartbeats every 10 seconds to reduce idle-disconnects.


Client Configuration Examples / 客户端接入示例

Antigravity (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "gemini-web-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gemini-web-mcp",
        "run",
        "gemini-web-mcp"
      ],
      "env": {
        "GEMINI_WEB_MCP_PROXY": "http://127.0.0.1:7890",
        "GEMINI_WEB_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Claude Code / Cursor

{
  "mcpServers": {
    "gemini-web-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Jefferyu/gemini-web-mcp.git",
        "gemini-web-mcp"
      ],
      "env": {
        "GEMINI_WEB_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

Progressive Disclosure Skill & Routing Templates / Skill 与路由规则模板

  • Copy examples/skills/gemini-web/SKILL.md to .agents/skills/gemini-web/SKILL.md (or ~/.gemini/config/skills/gemini-web/SKILL.md) for on-demand loading without permanent context bloat.

  • Copy or adapt examples/GEMINI.md into your project's GEMINI.md / AGENTS.md / CLAUDE.md.


Development / 本地开发与测试

uv sync --extra dev
uv run ruff check src tests
uv run mypy src
uv run pytest -v

License & Disclaimer / 协议与免责声明

  • Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE.

  • This project relies on gemini-webapi (AGPL-3.0) to interact with Google Gemini's web interface using user-supplied session cookies. It is not affiliated with or endorsed by Google. Use responsibly and in accordance with applicable terms of service.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to query Google AI (Gemini models) via Vertex AI or Google AI Studio with automatic tool selection, multi-turn reasoning, and multimodal input support.
      10
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with a signed-in Gemini web account through a local stdio MCP server for status, capabilities, models, prompts, history, conversations, memory, usage, and downloads.
      1
      MIT