gemini-web-mcp-cli 0.2.2

MCP server and CLI for the Gemini web interface

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.0 Pro, Flash, Flash Thinking, and more)
• Interactive REPL with slash commands, session persistence, and model switching
• Image generation via Nano Banana / Imagen
• Video generation via Veo 3.1
• Music generation via Lyria 3 with 16 style presets (8-bit, K-pop, Emo, Cinematic, and more)
• Deep Research with multi-source reports
• Gems management (custom system prompts)
• Multi-profile support with cross-product profile sharing (NotebookLM MCP)
• MCP server with 9 consolidated tools for AI agent integration
• Skill system to teach AI tools (Claude Code, Cursor, Codex, etc.) how to use gemcli
• Diagnostics (gemcli doctor) for installation, auth, and configuration checks
• One-command setup (gemcli setup add <tool>) for MCP client configuration

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]"

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:

Command	Description
/model <name>	Switch model (pro, flash, thinking)
/verify	Show server model hash
/new	Start new conversation
/save <file>	Export conversation
/history	View conversation turns
/help	Show help
/quit	Exit REPL

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

gemcli video "Ocean waves crashing on a rocky beach at sunset"
gemcli video "Dancing robot" -o robot.mp4

5. Generate Music (Lyria 3)

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 --list-styles                # Show all 16 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. Manage Gems

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

Profile Management

gemcli profile list                    # List profiles
gemcli profile create work             # Create new profile
gemcli profile switch work             # Switch active 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

Tool	Actions	Description
chat	send	Conversations with model selection and extensions
image	generate, download	Image creation (Nano Banana / Imagen)
video	generate, status, download	Video creation (Veo 3.1)
music	generate, list_styles, download	Music generation (Lyria 3) with 16 style presets
research	start, status	Deep Research with reports
gems	list, create, update, delete	Custom Gem management
canvas	create, update, export	Canvas documents (coming soon)
code	execute, download	Python sandbox (coming soon)
file	upload	File uploads for context (coming soon)

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, other (exports all formats).

Persistent Chrome (for background processes)

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. After a reboot, run gemcli chrome start again.

Which features need Chrome?

Feature	Chrome needed?
Chat (Flash)	No
Chat (Pro/Thinking)	Yes
Image generation	No
Video generation	No
Music generation	Yes (BotGuard required even on Flash)
Deep Research	No

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                  # 250 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