Gemini MCP (gemini-mcp)

A local Model Context Protocol (MCP) server that automates gemini.google.com using an authenticated browser profile via Playwright CDP.

Built specifically to unlock web-exclusive capabilities—including 4 Argon, 3.1 Pro, and Thinking Level depth controls—directly inside agentic workflows (Claude Desktop, Cursor, Hermes Agent, etc.).

Features

• Model Switching:

  • 4 Argon (Complex tasks / Deep reasoning) — Requires Gemini Advanced / Google One AI Premium (Pro) plan

  • 3.1 Pro (Advanced reasoning)

  • 3.8 Flash (All-around everyday tasks)

  • 3.5 Flash-Lite (Fastest responses)

• Thinking Depth:

  • Low (Quick & concise)

  • Medium (Balanced depth)

  • High (Extra thorough reasoning)

• Local File Uploads: Upload images, documents, and code files directly via gemini_upload_and_ask.

• Usage & Quota Monitoring: Check live consumption %, weekly limits, and reset timestamps via gemini_usage.

• Browser Profile Isolation: Defaults to a dedicated secondary profile (Profile 1) to ensure your main personal profile remains untouched.

• Headless & Headed Support: Automatically detects running CDP instances (default: 9333), launches headless via xvfb-run on Linux servers, or opens normally on desktop environments (Linux, macOS, Windows).

Related MCP server: Browser MCP

Exposed Tools

Prerequisites

1. Google Account with Pro Plan: To access 4 Argon, your account must be subscribed to Gemini Advanced / Google One AI Premium (Pro).

2. Node.js: v18.0.0 or higher.

3. Browser: Brave Browser (recommended) or Google Chrome.

4. (Optional - Linux Headless): If running on a headless Linux server without a display:

   sudo apt update && sudo apt install -y xvfb

Quick Start

1. Clone & Build

git clone https://github.com/ferrianes/gemini-mcp.git
cd gemini-mcp
npm install
npm run build

2. One-Time Google Authentication

Before running the MCP server, sign in to your Google Account on the designated browser profile once:

On Linux:

brave-browser --profile-directory="Profile 1" "https://gemini.google.com/app?hl=en"

On macOS:

open -a "Brave Browser" --args --profile-directory="Profile 1" "https://gemini.google.com/app?hl=en"

1. Log in to your Google account (with Gemini Advanced / Google One Pro access).

2. Complete 2FA / Passkey verification.

3. Once the Gemini chat interface loads, close the browser window. The session cookies will be saved in that profile.

MCP Configuration

Add gemini-mcp to your MCP client configuration (Claude Desktop, Cursor, Hermes Agent, etc.):

Option 1: Direct via npx (No manual clone needed)

Using GitHub repository directly:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": [
        "-y",
        "github:ferrianes/gemini-mcp"
      ]
    }
  }
}

Or via npm (if using the published @ferrianes/gemini-mcp package):

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": [
        "-y",
        "@ferrianes/gemini-mcp"
      ]
    }
  }
}

Option 2: Local Script (run.sh)

{
  "mcpServers": {
    "gemini": {
      "command": "/path/to/gemini-mcp/run.sh"
    }
  }
}

Environment Variables

You can customize behavior using the following environment variables:

License

This project is licensed under the MIT License.