gemini-web-mcp-cli

MCP server and CLI for the Gemini web interface. Reverse-engineers the Gemini web UI's RPC protocol to provide programmatic access to all Gemini features.

Features

• Chat with model selection (Gemini 3.7 Flash, Flash Extended, 3.1 Pro, and more)
• File upload for context in conversations (images, PDFs, documents, audio)
• Interactive REPL with slash commands, session persistence, and model switching
• Image generation via Nano Banana Pro / Nano Banana 2 with explicit aspect ratios (1:1, 9:16, 3:4, 4:3, 16:9)
• Video generation via Gemini Omni with orientation (landscape/portrait), model tiers, and templates
• Music generation via Lyria 3.5 with Length/Vocals/Genre controls, 24 templates, and 16 legacy style presets
• Deep Research with multi-source reports
• Usage limits checking with account/profile, per-feature usage %, credits left, and reset time — plus profile flipping when quota runs out
• Gems management (custom system prompts)
• Multi-profile support with cross-product profile sharing (NotebookLM MCP)
• MCP server with 10 consolidated tools for AI agent integration
• Skill system to teach AI tools (Claude Code, Cursor, Codex, etc.) how to use gemcli
• Hack Claude — launch Claude Code powered by Gemini (gemcli hack claude)
• API server — local Anthropic-compatible API backed by Gemini
• Diagnostics (gemcli doctor) for installation, auth, and configuration checks
• One-command setup (gemcli setup add <tool>) for MCP client configuration

Vibe Coding Alert

Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.

The goal here was to learn — both about building CLI tools in Python and about how modern web applications work under the hood. The code works, but it's very much a learning project, not a polished product.

If you know better, teach us. PRs, issues, and architectural advice are all welcome. This is open source specifically because human expertise is irreplaceable.

Educational & Research Use: This project reverse-engineers the Gemini web interface protocol for educational and research purposes. It is not affiliated with, endorsed by, or sponsored by Google. Use of this tool is at your own risk, and you are responsible for compliance with Google's Terms of Service. The authors assume no liability for how this software is used.

Installation

# With uv (recommended)
uv tool install gemini-web-mcp-cli

# With pip
pip install gemini-web-mcp-cli

# With pipx
pipx install gemini-web-mcp-cli

# Development
git clone https://github.com/jacob-bd/gemini-web-mcp-cli
cd gemini-web-mcp-cli
uv pip install -e ".[dev]"

Upgrading

# With uv
uv cache clean && uv tool install --force gemini-web-mcp-cli

# With pip
pip install --no-cache-dir --upgrade gemini-web-mcp-cli

# With pipx
pipx upgrade gemini-web-mcp-cli

Quick Start

1. Authenticate

gemcli login                  # Automated Chrome login via CDP
gemcli login --manual         # Paste cookies manually
gemcli login --check          # Validate current session

Automated login opens Chrome, navigates to gemini.google.com, and captures cookies via CDP. If you have a NotebookLM MCP profile, gemcli can reuse it automatically.

2. Chat

gemcli chat "What is the meaning of life?"
gemcli chat "Explain quantum computing" -m pro
gemcli chat "Summarize this" -o summary.md
gemcli chat                   # Interactive REPL

Interactive REPL commands:

3. Generate Images

gemcli image "A red panda wearing a top hat in a bamboo forest"
gemcli image "A futuristic city at sunset" -o city.png

4. Generate Videos (Gemini Omni)

gemcli video "Ocean waves crashing on a rocky beach at sunset"
gemcli video "Dancing robot" -o robot.mp4
gemcli video "A vertical story for Shorts" -O portrait -o story.mp4
gemcli video "A cinematic oner" -m pro -O landscape -o shot.mp4
gemcli video -T "Logo reveal" "NAIDA'S hair salon" -o logo.mp4

5. Generate Music (Lyria 3.5)

gemcli music "A comical R&B slow jam about a sock"
gemcli music "Cats playing video games" -s 8-bit -o track.mp3
gemcli music "Summer vibes" -s k-pop -o video.mp4 -f video
gemcli music "A chill study beat" -g lo-fi -L short
gemcli music "An upbeat ad jingle" -V vocals -g pop -T "Brand jingle" -o jingle.mp3
gemcli music --list-styles                # Show all 16 legacy style presets

Available style presets: 90s-rap, latin-pop, folk-ballad, 8-bit, workout, reggaeton, rnb-romance, kawaii-metal, cinematic, emo, afropop, forest-bath, k-pop, birthday-roast, folk-a-cappella, bad-music. Also accepts aliases like "rap", "metal", "ambient", "chiptune".

6. Deep Research

gemcli research "Latest advances in quantum computing 2026"
gemcli research "AI regulation landscape" -o report.md

7. File Upload (Chat with Attachments)

gemcli chat "Summarize this document" -f report.pdf
gemcli chat "What's in this image?" -f screenshot.png
gemcli chat "Compare these" -f file1.md -f file2.md
gemcli file upload document.pdf     # Upload only, get identifier

Supported file types: images (PNG, JPEG, GIF, WebP), PDFs, documents, audio files. Files are uploaded via Google's resumable upload protocol and attached to the chat message automatically.

8. Hack Claude (Use Gemini in Claude Code)

gemcli hack claude                    # Launch Claude Code with Gemini Flash
gemcli hack claude --model gemini-pro # Use Gemini Pro
gemcli hack claude -p "fix this bug" # Pass args through to Claude Code

Automatically starts a local Anthropic-compatible API server backed by Gemini, configures Claude Code to use it, and cleans up when done. Requires claude CLI to be installed.

9. Manage Gems

gemcli gems list
gemcli gems create --name "Code Reviewer" --prompt "You are an expert code reviewer..."
gemcli gems delete <gem-id>

10. Check Usage Limits

gemcli limits                    # Account/profile + per-feature usage % and credits left
gemcli -p work limits            # Check another account before flipping

Requires Chrome for browser cookie authentication. Output starts with the account and profile, then per-feature usage: the server-reported usage percentage, credits left in the plan pool (2400 credits per rolling ~5h window), and reset time. The live web view is https://gemini.google.com/usage. When a media tool is disabled because its usage is exhausted, retry with another profile (gemcli -p <profile> video ...).

Profile Management

gemcli profile list                    # List profiles
gemcli profile create work             # Create new profile
gemcli profile switch work             # Switch active profile
gemcli -p work limits                  # Check another account's quota
gemcli -p work video "..." -o clip.mp4 # Run any command as that profile
gemcli chat "hello" --profile work     # Use specific profile

Cross-product profile sharing: gemcli automatically discovers profiles from NotebookLM MCP (~/.notebooklm-mcp-cli/profiles/). No copying — profiles are read live.

Environment variable: GEMCLI_PROFILE=work overrides the active profile.

MCP Server Setup

Use gemcli setup to configure the MCP server for your AI tools in one command:

gemcli setup add cursor            # Configure Cursor
gemcli setup add claude-code       # Configure Claude Code
gemcli setup add claude-desktop    # Configure Claude Desktop
gemcli setup add gemini-cli        # Configure Gemini CLI
gemcli setup add windsurf          # Configure Windsurf
gemcli setup add cline             # Configure Cline
gemcli setup add antigravity       # Configure Antigravity
gemcli setup list                  # Show configuration status
gemcli setup remove cursor         # Remove configuration

Or add manually to your MCP client config:

{
  "mcpServers": {
    "gemini-web-mcp": {
      "command": "gemini-web-mcp",
      "args": []
    }
  }
}

Available MCP Tools

Skill System

Skills teach AI tools how to use gemcli effectively. Install a skill so your AI assistant knows all gemcli commands, workflows, and best practices.

gemcli skill install claude-code   # Install for Claude Code
gemcli skill install cursor        # Install for Cursor
gemcli skill install codex         # Install for Codex (AGENTS.md format)
gemcli skill install gemini-cli    # Install for Gemini CLI
gemcli skill list                  # Show installation status
gemcli skill update                # Update all installed skills
gemcli skill show                  # Display skill documentation
gemcli skill uninstall claude-code # Remove a skill

Supported tools: claude-code, cursor, codex, opencode, gemini-cli, antigravity, cline, openclaw, alef-agent, other (exports all formats).

Persistent Chrome (for background processes)

Image generation, video generation, music generation, and Pro/Thinking models require Chrome for BotGuard token generation. If running from a background process (macOS LaunchAgent, cron, systemd), Chrome cannot be launched on demand. Start it once from an interactive terminal:

gemcli chrome start              # Start headless Chrome daemon
gemcli chrome start --visible    # Start with visible window
gemcli chrome status             # Check health, port, auth status
gemcli chrome stop               # Stop the daemon

The daemon runs headless, survives terminal close, and is automatically detected by Token Factory. gemcli chrome status verifies both the Google auth cookie and Gemini's live SNlM0e page token; if the daemon drifts from auth.json, Token Factory will try to re-sync saved cookies into Chrome before falling back to login. After a reboot, run gemcli chrome start again.

Which features need Chrome?

Diagnostics

gemcli doctor              # Check installation, auth, and configuration
gemcli doctor --verbose    # Detailed diagnostics with paths and timestamps

The doctor command checks:

• Installation (gemcli and gemini-web-mcp binaries)
• Chrome (binary detection, saved profiles, persistent daemon status)
• Configuration (config directory, profiles, NotebookLM cross-product)
• Authentication (cookies and tokens for active profile)
• MCP clients (configuration status across all supported tools)
• Skills (installation status)

Verb-First Aliases

Alternative command syntax for convenience:

gemcli list gems               # = gemcli gems list
gemcli list profiles           # = gemcli profile list
gemcli list skills             # = gemcli skill list
gemcli create gem --name ...   # = gemcli gems create --name ...
gemcli delete gem <id>         # = gemcli gems delete <id>
gemcli install skill <tool>    # = gemcli skill install <tool>
gemcli update skill [tool]     # = gemcli skill update [tool]

AI-Friendly Documentation

gemcli --ai                    # Print full AI-friendly docs to stdout

Outputs complete documentation in a format optimized for AI assistants to read and understand the full CLI and MCP tool surface.

Architecture

src/gemini_web_mcp_cli/
    core/              # RPC transport, auth, parsing (shared foundation)
    services/          # Business logic (single source of truth)
    data/              # Skill documentation (ships with package)
    cli.py             # CLI (Click) — thin wrapper over services
    mcp.py             # MCP server (FastMCP) — thin wrapper over services
    setup.py           # MCP client configuration helper
    skill.py           # Skill installer for AI tools

All interfaces (CLI, MCP, future API) consume the same service layer. When Gemini changes an RPC, you update one service file and everything works.

Development

git clone https://github.com/jacob-bd/gemini-web-mcp-cli
cd gemini-web-mcp-cli
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest tests/ -v                  # 342 tests
ruff check src/ tests/            # Lint

Acknowledgments

Protocol knowledge informed by HanaokaYuzu/Gemini-API, an excellent reverse-engineering of the Gemini web interface. Clean-room rebuild following patterns from notebooklm-mcp-cli and perplexity-web-mcp.

License

MIT