Skip to main content
Glama
eLyiN
by eLyiN

Gemini Bridge

CI Status PyPI Version MIT License Python 3.10+ MCP Compatible Gemini CLI

AI 코딩 어시스턴트가 공식 CLI를 통해 Google Gemini AI와 상호 작용할 수 있도록 지원하는 경량 MCP(Model Context Protocol) 서버입니다. Claude Code, Cursor, VS Code 및 기타 MCP 호환 클라이언트와 함께 작동합니다. 단순성, 신뢰성 및 원활한 통합을 위해 설계되었습니다.

✨ 주요 기능

  • 직접적인 Gemini CLI 통합: 공식 Gemini CLI를 사용하여 API 비용 발생 없음

  • 3가지 MCP 도구: 기본 쿼리, 파일 분석 및 웹 검색 기능

  • 상태 비저장(Stateless) 운영: 세션, 캐싱 또는 복잡한 상태 관리 없음

  • 운영 준비 완료: 60초 타임아웃 설정이 가능한 강력한 오류 처리

  • 최소한의 의존성: mcp>=1.0.0 및 Gemini CLI만 필요

  • 쉬운 배포: uvx 및 기존 pip 설치 모두 지원

  • 범용 MCP 호환성: 모든 MCP 호환 AI 코딩 어시스턴트와 작동

  • 최신 Python: pathlib 및 최신 타입 힌트 사용 (Python 3.10+)

Related MCP server: Globalping

🚀 빠른 시작

사전 요구 사항

  1. Gemini CLI 설치:

    npm install -g @google/gemini-cli
  2. Gemini 인증:

    gemini auth login
  3. 설치 확인:

    gemini --version

설치

🎯 권장: PyPI 설치

# Install from PyPI
pip install gemini-bridge

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

대안: 소스에서 설치

# 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

개발용 설치

# 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

🌐 멀티 클라이언트 지원

Gemini Bridge는 모든 MCP 호환 AI 코딩 어시스턴트와 작동합니다 - 동일한 서버가 다양한 구성 방법을 통해 여러 클라이언트를 지원합니다.

지원되는 MCP 클라이언트

  • Claude Code ✅ (기본값)

  • Cursor ✅

  • VS Code ✅

  • Windsurf ✅

  • Cline ✅

  • Void ✅

  • Cherry Studio ✅

  • Augment ✅

  • Roo Code ✅

  • Zencoder ✅

  • 모든 MCP 호환 클라이언트 ✅

구성 예시

# 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

전역 구성 (~/.cursor/mcp.json):

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

프로젝트별 구성 (.cursor/mcp.json):

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

이동 경로: Settings → Cursor Settings → MCP → Add new global MCP server

구성 (.vscode/mcp.json):

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

대안: 확장 프로그램을 통한 설치

  1. 확장 프로그램 뷰 열기 (Ctrl+Shift+X)

  2. MCP 확장 프로그램 검색

  3. 다음 명령어로 사용자 지정 서버 추가: uvx gemini-bridge

Windsurf MCP 구성에 추가:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}
  1. Cline을 열고 상단 탐색 메뉴에서 MCP Servers 클릭

  2. Installed 탭 선택 → Advanced MCP Settings

  3. cline_mcp_settings.json에 추가:

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

이동 경로: Settings → MCP → Add MCP Server

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}
  1. Settings → MCP Servers → Add Server로 이동

  2. 서버 세부 정보 입력:

    • Name: gemini-bridge

    • Type: STDIO

    • Command: uvx

    • Arguments: ["gemini-bridge"]

  3. 구성 저장

UI 사용:

  1. 햄버거 메뉴 클릭 → Settings → Tools

  2. + Add MCP 버튼 클릭

  3. 명령 입력: uvx gemini-bridge

  4. 이름: Gemini Bridge

수동 구성:

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "gemini-bridge", 
      "command": "uvx", 
      "args": ["gemini-bridge"],
      "env": {}
    }
  ]
}
  1. Settings → MCP Servers → Edit Global Config로 이동

  2. mcp_settings.json에 추가:

{
  "mcpServers": {
    "gemini-bridge": {
      "command": "uvx",
      "args": ["gemini-bridge"],
      "env": {}
    }
  }
}
  1. Zencoder 메뉴 (...) → Tools → Add Custom MCP로 이동

  2. 구성 추가:

{
  "command": "uvx",
  "args": ["gemini-bridge"],
  "env": {}
}
  1. Install 버튼 클릭

pip 기반 설치:

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

개발/로컬 테스트:

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

npm 스타일 설치 (필요한 경우):

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

범용 사용법

클라이언트와 구성이 완료되면 다음 두 가지 도구를 동일하게 사용할 수 있습니다:

  1. 일반 질문: "이 코드베이스에서 사용되는 인증 패턴은 무엇인가요?"

  2. 특정 파일 분석: "보안 문제를 확인하기 위해 이 인증 파일들을 검토해 주세요"

서버 구현은 동일하며 - 클라이언트 구성만 다릅니다!

⚙️ 구성

타임아웃 구성

기본적으로 Gemini Bridge는 모든 CLI 작업에 60초 타임아웃을 사용합니다. 더 긴 쿼리(대용량 파일, 복잡한 분석)의 경우 GEMINI_BRIDGE_TIMEOUT 환경 변수를 사용하여 사용자 지정 타임아웃을 구성할 수 있습니다.

구성 예시:

# 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"
      }
    }
  }
}

타임아웃 옵션:

  • 기본값: 60초 (구성되지 않은 경우)

  • 범위: 양의 정수 (초 단위)

  • 호출별 재정의: 일회성 확장을 위해 도구에 timeout_seconds 제공

  • 권장: 대용량 파일 분석 시 120-300초

  • 잘못된 값: 경고와 함께 60초로 복귀

🛠️ 사용 가능한 도구

consult_gemini

단순 쿼리를 위한 직접 CLI 브리지.

매개변수:

  • query (string): Gemini에 보낼 질문 또는 프롬프트

  • directory (string): 쿼리를 위한 작업 디렉토리

  • model (string, 선택 사항): 사용할 모델 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" 또는 "auto" (기본값: "flash")

  • timeout_seconds (int, 선택 사항): 이 요청에 대한 실행 타임아웃 재정의

예시:

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

consult_gemini_with_files

상세 분석을 위해 파일 첨부 기능이 포함된 CLI 브리지.

매개변수:

  • query (string): Gemini에 보낼 질문 또는 프롬프트

  • directory (string): 쿼리를 위한 작업 디렉토리

  • files (list): 디렉토리 기준 상대 파일 경로 목록

  • model (string, 선택 사항): 사용할 모델 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" 또는 "auto" (기본값: "flash")

  • timeout_seconds (int, 선택 사항): 이 요청에 대한 실행 타임아웃 재정의

  • mode (string, 선택 사항): 파일 내용을 스트리밍하는 "inline"(기본값) 또는 Gemini CLI가 직접 @path 참조를 해결하도록 하는 "at_command"

예시:

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
)

팁: 대규모 트리 구조를 스캔할 때는 Gemini CLI가 파일 글로빙 및 잘림을 기본적으로 처리하도록 mode="at_command"로 전환하세요.

웹 검색 컨텍스트를 포함하여 Gemini에 질문합니다. 모델이 필요하다고 판단할 때 Gemini CLI의 자동 웹 검색을 사용합니다. 최선의 노력을 다하는 기능이며 모든 쿼리에 대해 보장되지는 않습니다.

매개변수:

  • query (string): 웹에서 검색할 검색어 또는 질문

  • directory (string): 명령 실행을 위한 작업 디렉토리

  • model (string, 선택 사항): 사용할 모델 - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite" 또는 "auto" (기본값: "flash")

  • timeout_seconds (int, 선택 사항): 이 요청에 대한 실행 타임아웃 재정의

예시:

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

📋 사용 예시

기본 코드 분석

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

상세 파일 검토

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

다중 파일 분석

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

웹 검색

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

대용량 파일 보호 장치

  • 인라인 전송은 중단을 방지하기 위해 파일당 약 256KB, 요청당 약 512KB로 제한됩니다.

  • 너무 큰 파일은 MCP 응답에 경고와 함께 헤드/테일 스니펫으로 잘립니다.

  • 환경 변수(GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES 등)로 제한을 조정하거나 더 큰 페이로드의 경우 mode="at_command"를 사용하세요.

🏗️ 아키텍처

핵심 설계

  • CLI 우선: gemini 명령에 대한 직접적인 하위 프로세스 호출

  • 상태 비저장: 각 도구 호출은 세션 상태 없이 독립적임

  • 적응형 타임아웃: 기본값은 60초이나 요청별 또는 환경 변수를 통해 재정의 가능

  • 첨부 파일 가드레일: 인라인 모드는 경량 제한을 적용하며, @ 모드는 Gemini CLI 도구에 위임

  • 간단한 오류 처리: 실패 시 즉시 중단하는 방식의 명확한 오류 메시지

프로젝트 구조

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

🔧 개발

로컬 테스트

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
gemini --version

Claude Code와의 통합

MCP 프로토콜을 통해 올바르게 구성되면 서버가 Claude Code와 자동으로 통합됩니다.

🔍 문제 해결

CLI를 사용할 수 없음

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

# Authenticate
gemini auth login

# Test
gemini --version

연결 문제

  • Gemini CLI가 올바르게 인증되었는지 확인

  • 네트워크 연결 확인

  • Claude Code MCP 구성이 올바른지 확인

  • gemini 명령이 PATH에 있는지 확인

일반적인 오류 메시지

  • "CLI not available": Gemini CLI가 설치되지 않았거나 PATH에 없음

  • "Authentication required": gemini auth login 실행

  • "Timeout after 60 seconds": 쿼리 시간이 너무 오래 걸림, 더 작은 단위로 나누어 시도

🤝 기여

커뮤니티의 기여를 환영합니다! 시작하는 방법에 대한 자세한 내용은 기여 가이드를 읽어보세요.

빠른 기여 가이드

  1. 저장소 포크

  2. 기능 브랜치 생성

  3. 변경 사항 적용

  4. 해당되는 경우 테스트 추가

  5. 풀 리퀘스트 제출

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🔄 버전 기록

자세한 버전 기록은 CHANGELOG.md를 참조하세요.

🆘 지원

  • 이슈: GitHub Issues를 통해 버그 보고 또는 기능 요청

  • 토론: 커뮤니티 토론 참여

  • 문서: docs/ 디렉토리에 추가 문서 생성 가능


초점: 공식 CLI를 통해 Claude Code와 Gemini AI를 연결하는 간단하고 신뢰할 수 있는 브리지.

Available Tools

3 tools
consult_geminiA

Send a query directly to the Gemini CLI.

Args:
    query: Prompt text forwarded verbatim to the CLI.
    directory: Working directory used for command execution.
    model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
    timeout_seconds: Optional per-call timeout override in seconds.

Returns:
    Gemini's response text or an explanatory error string.
ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo
queryYes
directoryYes
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses that the query is 'forwarded verbatim to the CLI', explains optional parameters (model, timeout), and describes the return value as 'Gemini's response text or an explanatory error string'. This provides sufficient behavioral context for a query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with Args/Returns sections and no extraneous content. It is concise but includes necessary parameter details. Minor tightening could improve it, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 params, 2 required) and presence of an output schema (implied by return description), the description covers the key behavioral aspects. It explains inputs, optional overrides, and return value, making it complete enough for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description carries the burden. It explains all four parameters: query (prompt text), directory (working directory), model (optional alias or ID), timeout_seconds (per-call override). This adds meaning beyond the schema's raw type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send a query directly to the Gemini CLI', specifying the verb (send) and resource (Gemini CLI). The name 'consult_gemini' and sibling tools 'consult_gemini_with_files' and 'web_search' help distinguish its purpose as a direct query without file context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly mention when to use this tool vs. 'consult_gemini_with_files' or 'web_search'. It only implies usage for direct queries without files, lacking alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

consult_gemini_with_filesA

Send a query to the Gemini CLI with file context.

Args:
    query: Prompt text forwarded to the CLI.
    directory: Working directory used for resolving relative file paths.
    files: File paths to include alongside the prompt. Paths must resolve
        inside ``directory``; entries pointing outside it are skipped.
    model: Optional model alias (``flash``, ``pro``) or full Gemini model id.
    timeout_seconds: Optional per-call timeout override in seconds.
    mode: ``"inline"`` streams truncated snippets; ``"at_command"`` emits
        ``@path`` directives so Gemini CLI resolves files itself.

Returns:
    Gemini's response or an explanatory error string with any warnings.
ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoinline
filesNo
modelNo
queryYes
directoryYes
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses that files outside the working directory are silently skipped, that errors are returned as explanatory strings with warnings, and that per-call timeouts are possible. It stops short of stating auth/network prerequisites or what triggers truncation limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded one-line summary followed by structured Args/Returns sections; each parameter line earns its place. The Returns block partially duplicates the output schema but is short enough not to be wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter external-CLI tool, all parameters and the path-safety rule are covered, and an output schema exists so return values need little prose. The main gap is the absent routing guidance versus consult_gemini and no discussion of limits when many/large files are passed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the schema even lacks enum metadata, so the description must compensate fully — and it does, defining mode values ('inline' streams truncated snippets vs 'at_command' emits @path directives), model aliases (flash/pro), the path-resolution constraint on files, and the purpose of directory and timeout overrides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Send a query to the Gemini CLI with file context'), which clearly separates it from the sibling consult_gemini that lacks file context. It is clear, but it never explicitly contrasts itself with that sibling or names when file context is needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use/when-not guidance or named alternative is given; the agent must infer from the tool name that files-bearing queries belong here rather than in consult_gemini. The mode explanation implies usage patterns but does not state selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.3.0
    • Addedweb_search
  2. 2 tool updatesv1.0.0
    • Changedconsult_gemini1 field changed
      • addedInput schema / properties / timeout_seconds
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "integer"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Timeout Seconds"
        +}
    • Changedconsult_gemini_with_files2 fields changed
      • addedInput schema / properties / mode
        Added value: +{
        +  "default": "inline",
        +  "title": "Mode",
        +  "type": "string"
        +}
      • addedInput schema / properties / timeout_seconds
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "integer"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Timeout Seconds"
        +}
  3. 2 tool updates
    • First observedconsult_gemini
    • First observedconsult_gemini_with_files

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation4/5

The three tools are mostly distinguishable: consult_gemini is plain, consult_gemini_with_files adds file context, and web_search adds search context. The overlap between the two consult_* tools is real—they differ only by file arguments—but the file/web/plain split gives an agent a reasonable basis for selection.

Naming Consistency4/5

Two tools follow a clean consult_gemini / consult_gemini_with_files pattern, and web_search is a readable verb_noun name. The only deviation is web_search not carrying the consult_ prefix, but it describes a genuinely different capability so it still reads consistently.

Tool Count4/5

Three tools is well-scoped for a thin bridge to a single CLI. Each tool maps to a distinct query mode rather than padding the surface, though the small count sits at the lower edge of the ideal range.

Completeness4/5

For a Gemini CLI passthrough the surface covers the main workflows: plain queries, file-context queries, and web-grounded queries. Minor gaps exist (no streaming/session continuity or config/inspection tool), but agents can accomplish the core task set without dead ends.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers