Gemini Bridge

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: MCP Gemini API Server

🚀 빠른 시작

사전 요구 사항

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": {}
}

3. 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"로 전환하세요.

web_search

웹 검색 컨텍스트를 포함하여 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를 연결하는 간단하고 신뢰할 수 있는 브리지.