<p align="center">
  <img src="assets/banner.png" alt="Gemini Web MCP & CLI" width="800">
</p>

# gemini-web-mcp-cli

MCP server and CLI for the [Gemini web interface](https://gemini.google.com). 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
- **Usage limits** checking with per-feature quota, remaining count, and reset time
- **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](https://policies.google.com/terms). The authors assume no liability for how this software is used.

## Installation

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
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

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

### 5. Generate Music (Lyria 3)

```bash
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

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

### 7. File Upload (Chat with Attachments)

```bash
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)

```bash
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

```bash
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

```bash
gemcli limits                    # Show usage quotas and remaining count
```

Requires Chrome for browser cookie authentication. Shows per-feature usage data including video, music, images, prompts, research, and more.

## Profile Management

```bash
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:

```bash
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:

```json
{
  "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 |
| `limits` | (none) | Check per-feature usage quotas, remaining count, and reset time |

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

```bash
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)

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:

```bash
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 | Yes (BotGuard + tool activation required) |
| Video generation | Yes (BotGuard + tool activation required) |
| Music generation | Yes (BotGuard required even on Flash) |
| Deep Research | No |

## Diagnostics

```bash
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:

```bash
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

```bash
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

```bash
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](https://github.com/HanaokaYuzu/Gemini-API), an excellent reverse-engineering of the Gemini web interface. Clean-room rebuild following patterns from [notebooklm-mcp-cli](https://github.com/jacob-bd/notebooklm-mcp-cli) and [perplexity-web-mcp](https://github.com/jacob-bd/perplexity-web-mcp).

## License

MIT
