gemini-web-mcp
Provides tools for interacting with the Google Gemini web app at gemini.google.com/app, enabling single- and multi-turn chat, dynamic model selection, local file uploads, recent chat listing, new chat creation, and authentication/status diagnostics through a persistent browser session.
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
English | Bahasa Indonesia
A plug-and-play Model Context Protocol (MCP) server built on Playwright / Patchright that wraps gemini.google.com/app using a persistent browser profile.
Connect it locally (stdio) to Antigravity (agy), Claude Code / Desktop, or Cursor, or deploy it as a remote Streamable HTTP MCP server on a headless Linux VPS / Homelab with built-in Xvfb + noVNC and Bearer Token authentication for autonomous orchestrators like Hermes Agent.
Key Features
Persistent Google Session: Sign in once (
--setup-auth); cookies and IndexedDB state stay persisted in your local profile directory or Docker volume.Anti-Bot / Stealth Ready: Prioritizes
patchrightalongside Chrome anti-automation flags to avoid Google's "This browser or app may not be secure" login block, and supports attaching to a running Chrome instance via--cdp-url.Single-Turn & Multi-Turn Chat (
gemini_chat): Resume any thread viaconversation_url, inject multi-line prompts atomically without prematureEntersubmission, detect streaming completion via DOM stability polling, and extract clean Markdown (preserving fenced code blocks and tables).Dynamic Model Switching (
gemini_select_model): Switch between Fast / Flash, Thinking, Pro, and other models available on your Google account.Multi-File Upload (
gemini_upload_files): Upload local PDFs, images, source code, documents, or videos directly into a Gemini conversation.Conversation History & Diagnostics (
gemini_list_recent_chats,gemini_new_chat,gemini_status): List recent threads from the Gemini sidebar and inspect live DOM selector health.Bundled Agent Skill (
skills/gemini-web-mcp/): Ready-to-installSKILL.md(English default + Bahasa Indonesia) for Claude Code, Antigravity, Cursor, and Hermes Agent.
Related MCP server: Remote Browser
Quick Start 1: Local Machine (Plug & Play)
Requires Python 3.11+. Clone the repository and run the one-command bootstrap script:
git clone https://github.com/ridloabelian/gemini-web-mcp.git
cd gemini-web-mcp
chmod +x scripts/bootstrap.sh
./scripts/bootstrap.shWhat scripts/bootstrap.sh does automatically:
Installs
uv(if missing) and syncs all package dependencies frompyproject.toml.Installs the Patchright Chromium binary.
Launches a headed browser window at
https://gemini.google.com/appfor your one-time Google sign-in.Prints a ready-to-paste MCP client JSON snippet with your exact local path.
Local MCP Client Configuration (stdio)
Add this entry to your MCP client configuration (.mcp.json, Claude Desktop, Cursor, or Antigravity):
{
"mcpServers": {
"gemini-web": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/gemini-web-mcp",
"gemini-web-mcp"
],
"env": {
"GEMINI_PROFILE_DIR": "~/.gemini-web-mcp/profile",
"GEMINI_HEADLESS": "true",
"GEMINI_BROWSER_CHANNEL": "chrome"
}
}
}
}Or run directly via uvx without keeping a local clone (once your profile directory has been authenticated with --setup-auth):
{
"mcpServers": {
"gemini-web": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ridloabelian/gemini-web-mcp.git",
"gemini-web-mcp"
]
}
}
}Installing the Bundled Agent Skill
This repository ships with a pre-built agent skill under skills/gemini-web-mcp/ (SKILL.md in English by default, plus SKILL.id.md in Bahasa Indonesia) teaching AI coding agents how to manage sessions, select models, and attach files reliably:
# Via Vercel / Agent Skills CLI
npx skills add ridloabelian/gemini-web-mcp
# Claude Code
cp -r skills/gemini-web-mcp ~/.claude/skills/
# Antigravity / Hermes Agent workspace
mkdir -p ~/.agent/skills && cp -r skills/gemini-web-mcp ~/.agent/skills/Quick Start 2: Headless VPS / Homelab Deployment (Docker + Xvfb + noVNC)
On headless Linux servers, the Docker image runs a real headed Chromium session inside an Xvfb (:99) virtual display—bypassing headless browser fingerprinting—paired with a localhost-bound noVNC portal for your initial Google login:
git clone https://github.com/ridloabelian/gemini-web-mcp.git
cd gemini-web-mcp
cp .env.example .env
# Set a strong secret in GEMINI_AUTH_TOKEN inside .env!
docker compose up -d --buildOne-Time Google Sign-In on a Remote Server:
Forward the noVNC port securely from your workstation over SSH:
ssh -L 6080:127.0.0.1:6080 user@your-server-ipOpen
http://localhost:6080/vnc.htmlin your local browser, click Connect, and complete the Google sign-in inside the Chromium window.Once signed in to Gemini, your session is persisted in the
gemini_profileDocker volume. You can disable noVNC afterward by settingENABLE_NOVNC=falsein.envand runningdocker compose up -d.
Remote MCP Client Configuration (StreamableHTTP)
The server exposes /mcp (Streamable HTTP) and /healthz (unauthenticated health probe) on port 8765. Behind a reverse proxy or Cloudflare Tunnel:
{
"mcpServers": {
"gemini-web-remote": {
"url": "https://your-mcp-domain.example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SECRET_GEMINI_AUTH_TOKEN"
}
}
}
}Available MCP Tools
Tool Name | Description |
| Opens an interactive headed browser window to complete one-time Google login and persist session state. |
| Sends a prompt (supports |
| Switches the active model in Gemini's mode switcher ( |
| Uploads one or more local files into the active Gemini thread, with an optional follow-up |
| Scrapes recent conversation titles and URLs from the |
| Opens a fresh conversation thread at |
| Checks authentication state, active model badge, current URL, and DOM selector health. |
Environment Variables (.env)
Variable | Default | Description |
|
| Persistent Chromium/Chrome user data directory. |
|
| Run browser headless ( |
|
| Browser channel ( |
| (empty) | Optional CDP endpoint to attach to an already-running Chrome instance (e.g., |
|
| Maximum wait time in seconds for streaming responses to complete. |
| (empty) | Optional Bearer token protecting HTTP/SSE MCP endpoints. |
Testing & CI
make testA GitHub Actions workflow template is included at examples/github-actions-ci.yml (copy to .github/workflows/ci.yml to enable automated checks on push/PR).
License
MIT License
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
Let your AI agent operate any website through a real, logged-in browser session.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables interaction with Gemini's web interface through MCP, with real-time streaming of responses and reasoning, stealth browser automation, proxy rotation, and session persistence.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to drive a live, persistent self-hosted Chromium session over MCP, running browser actions via Playwright/CDP, capturing page snapshots, screenshots and videos, and managing uploads and downloads in the same tabs and signed-in accounts a human user can take over at any time.28 npmApache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to perform real Chromium browser automation using Playwright-compatible tools, including persistent profiles, proxies, extensions, and humanized interactions over stdio or Streamable HTTP.280 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude or any MCP client to use the Google Gemini web app through a real Chrome browser with a normal Google account and no API key, including sending prompts, managing chats, uploading files, downloading results, and inspecting or interacting with pages via accessibility roles.145 npmMIT