Skip to main content
Glama

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 patchright alongside 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 via conversation_url, inject multi-line prompts atomically without premature Enter submission, 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-install SKILL.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.sh

What scripts/bootstrap.sh does automatically:

  1. Installs uv (if missing) and syncs all package dependencies from pyproject.toml.

  2. Installs the Patchright Chromium binary.

  3. Launches a headed browser window at https://gemini.google.com/app for your one-time Google sign-in.

  4. 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 --build

One-Time Google Sign-In on a Remote Server:

  1. Forward the noVNC port securely from your workstation over SSH:

    ssh -L 6080:127.0.0.1:6080 user@your-server-ip
  2. Open http://localhost:6080/vnc.html in your local browser, click Connect, and complete the Google sign-in inside the Chromium window.

  3. Once signed in to Gemini, your session is persisted in the gemini_profile Docker volume. You can disable noVNC afterward by setting ENABLE_NOVNC=false in .env and running docker 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

gemini_setup_auth

Opens an interactive headed browser window to complete one-time Google login and persist session state.

gemini_chat

Sends a prompt (supports new_chat, conversation_url, inline model selection, and file_paths attachments) and returns clean Markdown.

gemini_select_model

Switches the active model in Gemini's mode switcher (Flash, Thinking, Pro, etc.) and lists available options.

gemini_upload_files

Uploads one or more local files into the active Gemini thread, with an optional follow-up prompt.

gemini_list_recent_chats

Scrapes recent conversation titles and URLs from the gemini.google.com sidebar.

gemini_new_chat

Opens a fresh conversation thread at gemini.google.com/app.

gemini_status

Checks authentication state, active model badge, current URL, and DOM selector health.

Environment Variables (.env)

Variable

Default

Description

GEMINI_PROFILE_DIR

~/.gemini-web-mcp/profile

Persistent Chromium/Chrome user data directory.

GEMINI_HEADLESS

true

Run browser headless (false is recommended when running inside Docker Xvfb).

GEMINI_BROWSER_CHANNEL

chrome

Browser channel (chrome, msedge, or empty "" for bundled Chromium).

GEMINI_CDP_URL

(empty)

Optional CDP endpoint to attach to an already-running Chrome instance (e.g., http://127.0.0.1:9222).

GEMINI_RESPONSE_TIMEOUT

180

Maximum wait time in seconds for streaming responses to complete.

GEMINI_AUTH_TOKEN

(empty)

Optional Bearer token protecting HTTP/SSE MCP endpoints.

Testing & CI

make test

A 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT