gemini-web-mcp
Wraps Web Gemini (gemini.google.com) as an on-demand subagent, exposing multi-turn text and multimodal Q&A with model/thinking selection, persistent named sessions (list, get, delete, clear) backed by SQLite, cookie-based authentication with proxy support, attachment uploads with security guardrails, and health checks for auth, models, and connectivity.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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-labelasyncio.Lockso multiple IDE windows never clobber each other's sessions, while fullmetadatalists (3 or 4+ elements) are preserved verbatim.
Cross-Model
1050Guard / 跨模型防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) -> optionalbrowser-cookie3, coordinated withgemini-webapi's rotated1PSIDTScache.
Strict
stdioPurity /stdio零污染:Forces
loguruand stdlibloggingontosys.stderrat startup before importing third-party clients sostdoutcarries 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 MBdefault).
Pluggable Backend Architecture / 可插拔后端抽象:
Built around
GeminiBackendABC (CookieBackendtoday, 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(orcurl -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-mcpor~/.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-cookiesMode 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.jsonCursor:
~/.cursor/mcp.json(global) or.cursor/mcp.json(project)Claude Code:
claude mcp add ...or~/.claude.json/.mcp.jsonGemini 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 reachgemini.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.mdProject-local:
.agents/skills/gemini-web/SKILL.md
Claude Code:
Global:
~/.claude/skills/gemini-web/SKILL.mdProject-local:
.claude/skills/gemini-web/SKILL.md
Optional Routing Rule: Only if the user wants proactive routing in project rules, merge
examples/GEMINI.mdintoAGENTS.md/GEMINI.md/CLAUDE.md.
Step 5: Verify MCP Handshake & Guide Cookie Setup
Verify
stdioJSON-RPC purity by sending an MCPinitialize+tools/listpayload and confirminggemini_ask,gemini_sessions, andgemini_healthare returned cleanly onstdout.Check credential readiness (either via
gemini_healthafter restart, or runningCookieBackend(Settings()).health()).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.jsondirectly:{ "__Secure-1PSID": "paste-value-here", "__Secure-1PSIDTS": "paste-value-if-present" }Or, on macOS with Safari logged in and
--extra browser-cookiesenabled, 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-mcpOption 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-cookiesAuthentication & Cookies / 鉴权与 Cookie 获取
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 tocookies.jsonor environment variables is the most reliable setup.
Method A: ~/.config/gemini-web-mcp/cookies.json (Recommended)
Log in to
https://gemini.google.comin your browser.Open DevTools (
Application->Cookies->https://gemini.google.com) or a cookie exporter extension, and copy__Secure-1PSIDand (if present)__Secure-1PSIDTS.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 |
| Fallback to | HTTP/SOCKS proxy URL passed to |
|
| Default model ( |
|
| Path to JSON cookie file |
|
| Path to SQLite WAL session store |
|
| Standard request timeout (seconds) |
|
| Timeout when |
|
| Max attachments per |
|
| Max size per attachment (MB) |
|
|
|
Client Timeout Tip: For
model="thinking"or large file uploads, configure your MCP client's tool call timeout >=300seconds if supported.gemini-web-mcpemits 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.mdto.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.mdinto your project'sGEMINI.md/AGENTS.md/CLAUDE.md.
Development / 本地开发与测试
uv sync --extra dev
uv run ruff check src tests
uv run mypy src
uv run pytest -vLicense & 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Durable memory, headless browser and research for agents. Pay per call: x402 USDC on Base or credits
Cloud browsers for AI agents: get past bot detection, sign in with MFA, run web tasks at scale.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to consult Gemini for complex coding problems with session management, file attachments, and conversation persistence.106MIT
- AlicenseAqualityCmaintenanceEnables 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.10Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables Google Antigravity and MCP-compatible clients to delegate complex coding and reasoning tasks to a high-reasoning Gemini model through a persistent Chromium session, preserving Gemini Web history and audit logs.MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT