gemini-web-mcp-cli 0.3.1

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)
• 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 / 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
• 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]"

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

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, extensions, and file attachments
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 conversation context

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
Chat with file attachments	Yes (BotGuard required)
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                  # 308 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