Metadata-Version: 2.4
Name: gemini-web-mcp-cli
Version: 0.1.3
Summary: MCP server and CLI for the Gemini web interface
Project-URL: Homepage, https://github.com/jacob-bd/gemini-web-mcp-cli
Project-URL: Repository, https://github.com/jacob-bd/gemini-web-mcp-cli
Project-URL: Issues, https://github.com/jacob-bd/gemini-web-mcp-cli/issues
Project-URL: Changelog, https://github.com/jacob-bd/gemini-web-mcp-cli/blob/main/CHANGELOG.md
Author: Jacob Ben David
License-Expression: MIT
Keywords: ai,cli,gemini,google,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: loguru>=0.7
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: orjson>=3.9
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: websocket-client>=1.7
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.3; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# 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)
- **Interactive REPL** with slash commands, session persistence, and model switching
- **Image generation** via Nano Banana / Imagen
- **Video generation** via Veo 3.1
- **Deep Research** with multi-source reports
- **Gems** management (custom system prompts)
- **Multi-profile** support with cross-product profile sharing (NotebookLM MCP)
- **MCP server** with 8 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

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

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

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

### 6. Manage Gems

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

## 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 and extensions |
| `image` | generate, download | Image creation (Nano Banana / Imagen) |
| `video` | generate, status, download | Video creation (Veo 3.1) |
| `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.

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

## 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)
- 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                  # 203 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
