Gemini Web MCP

A layered MCPServer and Codex skill for Gemini Web workflows.

English · 简体中文

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 MCP protocol behavior — discovery, version negotiation, JSON-RPC framing, the legacy initialize handshake, result validation, and structured protocol errors — to the official mcp Python SDK v2 through a dedicated MCPServer adapter. It contains no custom protocol stack; the codes in error_handler.py (NO_COOKIE, INVALID_COOKIE, SESSION_NOT_FOUND, …) are application-level errors returned in tool content, not JSON-RPC protocol errors.

The supported runtime is mcp>=2,<3 plus mcp-types>=2,<3. CI exercises both current server/discover clients on protocol 2026-07-28 and compatibility clients using the 2025-11-25 initialize path. Every tool advertises an outputSchema and returns validated structuredContent while retaining its existing text. See the explicit SDK/client compatibility and v1 end-of-support policy.

Install The Runtime Skill

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

npx --yes [email protected] add \
  https://github.com/Luckycat133/gemini-web-mcp \
  --skill gemini-web-mcp \
  --agent codex --copy --yes

This runtime skill teaches an agent how to operate the installed tools safely. Repository contributors should install the separate development skill:

npx --yes [email protected] add \
  https://github.com/Luckycat133/gemini-web-mcp \
  --skill gemini-web-mcp-development \
  --agent codex --copy --yes

The two roles are intentionally separate: gemini-web-mcp is for tool use; gemini-web-mcp-development owns implementation, tests, packaging, compatibility, and releases. Both public paths have byte-identical local mirrors enforced by CI.

Install The MCP Server

One-command, credential-free proof (requires uv):

uvx --from git+https://github.com/Luckycat133/gemini-web-mcp@main gemini-mcp-onboarding

This installs into an isolated environment, starts the real stdio server with the model profile, and calls the static text manifest without forwarding Gemini Cookies or making a Gemini request. Pin @main to a reviewed commit SHA for immutable installs.

Minimal MCP client configuration: