Gemini Bridge

Ein leichtgewichtiger MCP-Server (Model Context Protocol), der es KI-Programmierassistenten ermöglicht, über das offizielle CLI mit Googles Gemini-KI zu interagieren. Funktioniert mit Claude Code, Cursor, VS Code und anderen MCP-kompatiblen Clients. Entwickelt für Einfachheit, Zuverlässigkeit und nahtlose Integration.

✨ Funktionen

• Direkte Gemini CLI-Integration: Keine API-Kosten durch Nutzung des offiziellen Gemini CLI

• Drei MCP-Tools: Grundlegende Abfragen, Dateianalyse und Websuchfunktionen

• Zustandsloser Betrieb: Keine Sitzungen, kein Caching oder komplexes Zustandsmanagement

• Produktionsbereit: Robuste Fehlerbehandlung mit konfigurierbaren 60-Sekunden-Timeouts

• Minimale Abhängigkeiten: Erfordert nur mcp>=1.0.0 und das Gemini CLI

• Einfache Bereitstellung: Unterstützung für uvx und traditionelle pip-Installation

• Universelle MCP-Kompatibilität: Funktioniert mit jedem MCP-kompatiblen KI-Programmierassistenten

• Modernes Python: Verwendet pathlib und moderne Typ-Hinweise (Python 3.10+)

Related MCP server: MCP Gemini API Server

🚀 Schnellstart

Voraussetzungen

1. Gemini CLI installieren:

   npm install -g @google/gemini-cli

2. Bei Gemini authentifizieren:

   gemini auth login

3. Installation überprüfen:

   gemini --version

Installation

🎯 Empfohlen: PyPI-Installation

# Install from PyPI
pip install gemini-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Alternative: Aus dem Quellcode

# Clone the repository
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

Entwicklungsinstallation

# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add gemini-bridge-dev -s user -- python -m src

🌐 Multi-Client-Unterstützung

Gemini Bridge funktioniert mit jedem MCP-kompatiblen KI-Programmierassistenten – derselbe Server unterstützt mehrere Clients durch verschiedene Konfigurationsmethoden.

Unterstützte MCP-Clients

• Claude Code ✅ (Standard)

• Cursor ✅

• VS Code ✅

• Windsurf ✅

• Cline ✅

• Void ✅

• Cherry Studio ✅

• Augment ✅

• Roo Code ✅

• Zencoder ✅

• Jeder MCP-kompatible Client ✅

Konfigurationsbeispiele

# Recommended installation
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

# Development installation
claude mcp add gemini-bridge-dev -s user -- python -m src

Globale Konfiguration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Projektspezifisch (.cursor/mcp.json in Ihrem Projekt):

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Gehen Sie zu: Settings → Cursor Settings → MCP → Add new global MCP server

Konfiguration (.vscode/mcp.json in Ihrem Arbeitsbereich):

{
  "servers": {
    "gemini-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gemini-bridge"]
    }
  }
}

Alternative: Über Erweiterungen

1. Erweiterungsansicht öffnen (Strg+Umschalt+X)

2. Nach MCP-Erweiterungen suchen

3. Benutzerdefinierten Server hinzufügen mit dem Befehl: uvx gemini-bridge

Fügen Sie dies zu Ihrer Windsurf MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Öffnen Sie Cline und klicken Sie in der oberen Navigation auf MCP Servers

2. Wählen Sie den Tab Installed → Advanced MCP Settings

3. Fügen Sie dies zu cline_mcp_settings.json hinzu:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

Gehen Sie zu: Settings → MCP → Add MCP Server

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Navigieren Sie zu Settings → MCP Servers → Add Server

2. Füllen Sie die Serverdetails aus:

   • Name: gemini-bridge

   • Type: STDIO

   • Command: uvx

   • Arguments: ["gemini-bridge"]

3. Speichern Sie die Konfiguration

Über die Benutzeroberfläche:

1. Klicken Sie auf das Hamburger-Menü → Settings → Tools

2. Klicken Sie auf den Button + Add MCP

3. Geben Sie den Befehl ein: uvx gemini-bridge

4. Name: Gemini Bridge

Manuelle Konfiguration:

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "gemini-bridge", 
      "command": "uvx", 
      "args": ["gemini-bridge"],
      "env": {}
    }
  ]
}

1. Gehen Sie zu Settings → MCP Servers → Edit Global Config

2. Fügen Sie dies zu mcp_settings.json hinzu:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}

1. Gehen Sie zum Zencoder-Menü (...) → Tools → Add Custom MCP

2. Fügen Sie die Konfiguration hinzu:

{
  "command": "uvx",
  "args": ["gemini-bridge"],
  "env": {}
}

3. Klicken Sie auf den Install-Button

Für pip-basierte Installationen:

{
  "command": "gemini-bridge",
  "args": [],
  "env": {}
}

Für Entwicklung/lokales Testen:

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/gemini-bridge"
}

Für npm-artige Installation (falls erforderlich):

{
  "command": "npx",
  "args": ["gemini-bridge"],
  "env": {}
}

Universelle Verwendung

Sobald die Konfiguration mit einem Client erfolgt ist, verwenden Sie dieselben zwei Tools:

1. Allgemeine Fragen stellen: "Welche Authentifizierungsmuster werden in dieser Codebasis verwendet?"

2. Spezifische Dateien analysieren: "Überprüfe diese Authentifizierungsdateien auf Sicherheitsprobleme"

Die Serverimplementierung ist identisch – nur die Client-Konfiguration unterscheidet sich!

⚙️ Konfiguration

Timeout-Konfiguration

Standardmäßig verwendet Gemini Bridge ein 60-Sekunden-Timeout für alle CLI-Operationen. Für längere Abfragen (große Dateien, komplexe Analysen) können Sie ein benutzerdefiniertes Timeout über die Umgebungsvariable GEMINI_BRIDGE_TIMEOUT konfigurieren.

Beispielkonfigurationen:

# Add with custom timeout (120 seconds)
claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {
        "GEMINI_BRIDGE_TIMEOUT": "120"
      }
    }
  }
}

Timeout-Optionen:

• Standard: 60 Sekunden (falls nicht konfiguriert)

• Bereich: Jede positive Ganzzahl (Sekunden)

• Überschreibung pro Aufruf: Geben Sie timeout_seconds für ein Tool für einmalige Erweiterungen an

• Empfohlen: 120-300 Sekunden für die Analyse großer Dateien

• Ungültige Werte: Rückfall auf 60 Sekunden mit Warnung

🛠️ Verfügbare Tools

consult_gemini

Direkte CLI-Brücke für einfache Abfragen.

Parameter:

• query (string): Die Frage oder der Prompt, der an Gemini gesendet werden soll

• directory (string): Arbeitsverzeichnis für die Abfrage

• model (string, optional): Zu verwendendes Modell - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" oder "auto" (Standard: "flash")

• timeout_seconds (int, optional): Überschreiben des Ausführungs-Timeouts für diese Anfrage

Beispiel:

consult_gemini(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    model="flash"
)

consult_gemini_with_files

CLI-Brücke mit Dateianhängen für detaillierte Analysen.

Parameter:

• query (string): Die Frage oder der Prompt, der an Gemini gesendet werden soll

• directory (string): Arbeitsverzeichnis für die Abfrage

• files (list): Liste der Dateipfade relativ zum Verzeichnis

• model (string, optional): Zu verwendendes Modell - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" oder "auto" (Standard: "flash")

• timeout_seconds (int, optional): Überschreiben des Ausführungs-Timeouts für diese Anfrage

• mode (string, optional): Entweder "inline" (Standard), um Dateiinhalte zu streamen, oder "at_command", damit das Gemini CLI @path-Referenzen selbst auflöst

Beispiel:

consult_gemini_with_files(
    query="Analyze these auth files and suggest improvements",
    directory="/path/to/project",
    files=["src/auth.py", "src/models.py"],
    model="pro",
    timeout_seconds=180
)

Tipp: Beim Scannen großer Bäume wechseln Sie zu mode="at_command", damit das Gemini CLI das File-Globbing und die Kürzung nativ übernimmt.

web_search

Stellen Sie Gemini Fragen mit Websuchkontext. Verwendet die automatische Websuche des Gemini CLI, wenn das Modell feststellt, dass dies erforderlich ist. Best-Effort-Funktionalität - nicht für jede Abfrage garantiert.

Parameter:

• query (string): Suchanfrage oder Frage, die im Web nachgeschlagen werden soll

• directory (string): Arbeitsverzeichnis für die Befehlsausführung

• model (string, optional): Zu verwendendes Modell - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" oder "auto" (Standard: "flash")

• timeout_seconds (int, optional): Überschreiben des Ausführungs-Timeouts für diese Anfrage

Beispiel:

web_search(
    query="latest Python version and new features",
    model="flash"
)

📋 Anwendungsbeispiele

Grundlegende Codeanalyse

# Simple research query
consult_gemini(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

Detaillierte Dateiüberprüfung

# Analyze specific files
consult_gemini_with_files(
    query="Review these files and suggest security improvements",
    directory="/Users/dev/my-project",
    files=["src/auth.py", "src/middleware.py"],
    model="pro"
)

Analyse mehrerer Dateien

# Compare multiple implementation files
consult_gemini_with_files(
    query="Compare these database implementations and recommend the best approach",
    directory="/Users/dev/my-project",
    files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"],
    mode="at_command"
)

Websuche

# Get current information from the web
web_search(
    query="latest Python version and new features in 3.13",
    model="flash"
)

Sicherheitsvorkehrungen für große Dateien

• Inline-Übertragungen sind auf ca. 256 KB pro Datei und 512 KB pro Anfrage begrenzt, um Hänger zu vermeiden.

• Übergroße Dateien werden auf Kopf-/Fußzeilen-Snippets gekürzt, mit einer Warnung in der MCP-Antwort.

• Passen Sie die Obergrenzen mit Umgebungsvariablen an (GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES usw.) oder bevorzugen Sie mode="at_command" für größere Payloads.

🏗️ Architektur

Kerndesign

• CLI-First: Direkte Subprozessaufrufe an den gemini-Befehl

• Zustandslos: Jeder Tool-Aufruf ist unabhängig ohne Sitzungszustand

• Adaptives Timeout: Standardmäßig 60 Sekunden, aber pro Anfrage oder über Umgebungsvariable überschreibbar

• Anhang-Schutzmechanismen: Der Inline-Modus erzwingt leichtgewichtige Limits; der @-Modus delegiert an die Gemini CLI-Tools

• Einfache Fehlerbehandlung: Klare Fehlermeldungen mit Fail-Fast-Ansatz

Projektstruktur

gemini-bridge/
├── src/
│   ├── __init__.py              # Entry point
│   ├── __main__.py              # Module execution entry point
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml              # Python package configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policies
├── CHANGELOG.md               # Version history
└── LICENSE                    # MIT license

🔧 Entwicklung

Lokales Testen

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
gemini --version

Integration mit Claude Code

Der Server integriert sich automatisch in Claude Code, wenn er ordnungsgemäß über das MCP-Protokoll konfiguriert ist.

🔍 Fehlerbehebung

CLI nicht verfügbar

# Install Gemini CLI
npm install -g @google/gemini-cli

# Authenticate
gemini auth login

# Test
gemini --version

Verbindungsprobleme

• Überprüfen Sie, ob das Gemini CLI ordnungsgemäß authentifiziert ist

• Überprüfen Sie die Netzwerkkonnektivität

• Stellen Sie sicher, dass die Claude Code MCP-Konfiguration korrekt ist

• Überprüfen Sie, ob sich der gemini-Befehl in Ihrem PATH befindet

Häufige Fehlermeldungen

• "CLI not available": Gemini CLI ist nicht installiert oder nicht im PATH

• "Authentication required": Führen Sie gemini auth login aus

• "Timeout after 60 seconds": Die Abfrage hat zu lange gedauert, versuchen Sie, sie in kleinere Teile zu zerlegen

🤝 Mitwirken

Wir freuen uns über Beiträge aus der Community! Bitte lesen Sie unsere Contributing Guidelines für Details zum Einstieg.

Kurzanleitung für Beiträge

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch

3. Nehmen Sie Ihre Änderungen vor

4. Fügen Sie ggf. Tests hinzu

5. Senden Sie einen Pull Request

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE-Datei für Details.

🔄 Versionsverlauf

Siehe CHANGELOG.md für einen detaillierten Versionsverlauf.

🆘 Support

• Issues: Melden Sie Fehler oder fordern Sie Funktionen über GitHub Issues an

• Diskussionen: Treten Sie der Community-Diskussion bei

• Dokumentation: Zusätzliche Dokumente können im docs/-Verzeichnis erstellt werden

Fokus: Eine einfache, zuverlässige Brücke zwischen Claude Code und Gemini-KI über das offizielle CLI.