gemini-web-mcp

<p align="center"> <img src="docs/assets/gemini-web-mcp-banner.svg" alt="Gemini Web MCP" width="100%"> </p> <h1 align="center">Gemini Web MCP</h1> <p align="center"> A layered FastMCP server and Codex skill for Gemini Web workflows. </p> <p align="center"> <a href="https://github.com/Luckycat133/gemini-web-mcp/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/Luckycat133/gemini-web-mcp?label=release"></a> <a href="https://github.com/Luckycat133/gemini-web-mcp/tree/main/.agents/skills/gemini-web-mcp"><img alt="Codex Skill" src="https://img.shields.io/badge/Codex%20Skill-installable-0B6BFF"></a> <a href="https://www.gnu.org/licenses/agpl-3.0.html"><img alt="License" src="https://img.shields.io/badge/License-AGPL--3.0--only-blue.svg"></a> <a href="docs/changelog.md"><img alt="Verified" src="https://img.shields.io/badge/tests-1108%20passing-1F8A70"></a> </p> <p align="center"> <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a> </p>

Status: Active Development — Flagship Public Project

Disclaimer: this project is for technical research and educational use. It uses reverse-engineered Gemini Web behavior, which may violate Google service terms and may put accounts at risk. Use it at your own discretion.

What It Does

Gemini Web MCP exposes Gemini Web capabilities to MCP-compatible clients such as Codex, Claude Desktop, VS Code MCP clients, and other agent runtimes.

The main design choice is controlled tool layering. Agents should not see every private, account-level, or destructive operation by default. This server ships narrow GEMINI_TOOLS profiles, facade tools, MCP annotations, and a public Codex skill that tells agents how to choose the right surface.

MCP Protocol Compatibility

This server delegates all MCP protocol behavior — version negotiation, JSON-RPC framing, the initialize handshake, server/discover, structured error codes — to the official mcp Python SDK via FastMCP. It contains no protocol-layer code of its own; the codes in error_handler.py (NO_COOKIE, INVALID_COOKIE, SESSION_NOT_FOUND, …) are application-level errors returned as TextContent, not JSON-RPC protocol errors.

The pinned mcp 1.28.x line speaks protocol 2025-11-25 (and earlier). The MCP 2026-07-28 revision (stateless core, mandatory server/discover, resultType, reserved error range -32020..-32099, Roots/Sampling/Logging deprecated) requires mcp SDK v2.0.0+, which is a breaking major release (FastMCP → MCPServer, mcp.server.fastmcp removed, camelCase → snake_case fields, httpx → httpx2). Until that migration lands, pyproject.toml caps mcp at <2 per the SDK migration guide so fresh installs do not pull the incompatible v2.

Install The Codex Skill

Install the public skill with the cross-agent skills CLI:

npx skills add https://github.com/Luckycat133/gemini-web-mcp/tree/main/.agents/skills/gemini-web-mcp

The CLI can install the skill for Codex, Claude Code, Gemini CLI, Cline, and other supported agents. The skill lives at .agents/skills/gemini-web-mcp; the local development copy at .codex/skills/gemini-web-mcp is kept byte-for-byte identical by tests.

Install The MCP Server

Fastest verified path (requires uv):

GEMINI_TOOLS=model uvx \
  --from https://github.com/Luckycat133/gemini-web-mcp/releases/download/v1.3.0/gemini_mcp_server-1.3.0-py3-none-any.whl \
  gemini-mcp-server

Minimal MCP client configuration:

{
  "mcpServers": {
    "gemini": {
      "command": "uvx",
      "args": [
        "--from",
        "https://github.com/Luckycat133/gemini-web-mcp/releases/download/v1.3.0/gemini_mcp_server-1.3.0-py3-none-any.whl",
        "gemini-mcp-server"
      ],
      "env": {
        "GEMINI_TOOLS": "core"
      }
    }
  }
}

For local devel