cd ..

Gemini MCP Tool: Claude Code에서 Gemini의 거대 토큰 윈도우를 활용하는 방법

# Claude Code # Gemini # MCP # Developer Tools
정석
Gemini Tool MCP server

Claude Code는 강력한 AI 코딩 어시스턴트지만, 토큰 윈도우의 한계는 피할 수 없는 현실입니다. 특히 대규모 코드베이스나 긴 문서를 분석할 때 이 한계가 더욱 두드러집니다.

Gemini MCP Tool은 이 문제를 Model Context Protocol(MCP) 서버로 Gemini CLI를 래핑하는 방식으로 해결합니다. Claude Code 내에서 Gemini의 거대 토큰 윈도우(최대 2M 토큰)를 활용할 수 있게 해줍니다.

1) 왜 MCP 서버로 Gemini를 래핑할까

1.1 토큰 윈도우의 현실

모델토큰 윈도우
Claude 3.5 Sonnet200K
Gemini 2.5 Pro1M+
Gemini 2.5 Flash1M+

Gemini의 토큰 윈도우는 Claude의 5배 이상입니다. 이는 전체 코드베이스를 한 번에 분석하거나, 긴 문서를 요약할 때 결정적인 차이를 만듭니다.

1.2 SDK가 아닌 CLI 래핑

이 프로젝트는 Gemini SDK를 직접 사용하지 않고 Gemini CLI를 래핑합니다.

// geminiExecutor.ts 핵심 로직
const args = [];
if (model) { args.push(CLI.FLAGS.MODEL, model); }
if (sandbox) { args.push(CLI.FLAGS.SANDBOX); }
args.push(CLI.FLAGS.PROMPT, finalPrompt);

return await executeCommand(CLI.COMMANDS.GEMINI, args, onProgress);

이 방식의 장점:

2) 아키텍처 분석

2.1 MCP 서버 구조

// index.ts
const server = new Server(
  {
    name: "gemini-cli-mcp",
    version: "1.1.4",
  },
  {
    capabilities: {
      tools: {},
      prompts: {},
      notifications: {},
      logging: {},
    },
  },
);

MCP 서버는 세 가지 핵심 기능을 제공합니다:

기능설명
toolsask-gemini, brainstorm, sandbox-test 등
prompts미리 정의된 프롬프트 템플릿
notifications진행 상황 알림

2.2 Progress Notification

긴 작업 동안 클라이언트가 멈춘 것처럼 보이지 않도록 25초마다 진행 상황을 알림합니다.

// constants.ts
KEEPALIVE_INTERVAL: 25000, // 25 seconds

// index.ts
const progressInterval = setInterval(async () => {
  if (isProcessing && progressToken) {
    progress += 1;
    await sendProgressNotification(progressToken, progress, undefined, message);
  }
}, PROTOCOL.KEEPALIVE_INTERVAL);

2.3 자동 Quota 폴백

Gemini 2.5 Pro 할당량이 초과되면 자동으로 Flash 모델로 전환합니다.

if (errorMessage.includes(ERROR_MESSAGES.QUOTA_EXCEEDED) && model !== MODELS.FLASH) {
  Logger.warn(`${ERROR_MESSAGES.QUOTA_EXCEEDED}. Falling back to ${MODELS.FLASH}.`);
  // Flash 모델로 재시도
  fallbackArgs.push(CLI.FLAGS.MODEL, MODELS.FLASH);
  return await executeCommand(CLI.COMMANDS.GEMINI, fallbackArgs, onProgress);
}

3) 핵심 기능 분석

3.1 @ 문법으로 파일 참조

Gemini CLI의 @ 문법을 그대로 사용해 파일을 참조합니다.

ask gemini to analyze @src/main.js and explain what it does
use gemini to summarize @. the current directory
// 프롬프트 전처리에서 @ 유지
const finalPrompt = prompt_processed.includes('@') && !prompt_processed.startsWith('"')
  ? `"${prompt_processed}"`
  : prompt_processed;

3.2 샌드박스 모드

-s 플래그로 안전한 코드 실행 환경을 제공합니다.

sandbox: z.boolean().default(false)
  .describe("Use sandbox mode (-s flag) to safely test code changes...")

if (sandbox) { args.push(CLI.FLAGS.SANDBOX); }

사용 예시:

3.3 Change Mode: 구조화된 편집 제안

가장 흥미로운 기능입니다. Gemini가 OLD/NEW 형식으로 편집을 제안하면, Claude가 이를 직접 적용할 수 있습니다.

// changeModeParser.ts에서 파싱
// OUTPUT FORMAT:
// **FILE: [filename]:[line_number]**
// ````
// OLD:
// [exact code to be replaced]
// NEW:
// [new code to insert]
// ````

작동 방식:

  1. changeMode: true로 Gemini에 요청
  2. Gemini가 OLD/NEW 형식으로 응답
  3. 파서가 편집 내용을 추출
  4. 청크 단위로 분할 (편집이 많을 때)
  5. Claude가 각 청크를 순차적으로 적용
// 청킹 로직
const chunks = chunkChangeModeEdits(edits);
if (chunks.length > 1 && prompt) {
  cacheKey = cacheChunks(prompt, chunks);
}

3.4 Brainstorm 툴: 구조화된 아이디어 생성

단순한 질문이 아니라, 체계적인 브레인스토밍 프레임워크를 적용합니다.

methodology: z.enum([
  'divergent',      // 많은 아이디어 생성
  'convergent',     // 기존 아이디어 정제
  'scamper',        // 체계적 창의성 트리거
  'design-thinking', // 사용자 중심
  'lateral',        // 예상치 못한 연결
  'auto'            // AI가 선택
])

프롬프트 엔지니어링:

let enhancedPrompt = `# BRAINSTORMING SESSION

## Core Challenge
${prompt}

## Methodology Framework
${frameworkInstructions}

## Output Requirements
- Generate ${ideaCount} distinct, creative ideas
- Each idea should be unique and non-obvious
${includeAnalysis ? `
## Analysis Framework
- **Feasibility:** Implementation difficulty (1-5 scale)
- **Impact:** Potential value/benefit (1-5 scale)
- **Innovation:** Uniqueness/creativity (1-5 scale)
` : ''}
`;

4) 실제 사용 시나리오

시나리오 1: 대규모 코드베이스 분석

use gemini to analyze @src/ and identify architectural issues

Claude의 토큰 한계를 넘어서는 전체 소스 디렉토리를 Gemini가 분석합니다.

시나리오 2: 안전한 코드 테스트

use gemini sandbox to test @experimental.py with various inputs

샌드박스에서 위험할 수 있는 코드를 안전하게 실행합니다.

시나리오 3: 구조화된 리팩토링

use gemini with change mode to refactor @utils.js for better error handling

Gemini가 OLD/NEW 형식으로 편집을 제안하면, Claude가 이를 파일에 적용합니다.

시나리오 4: 창의적 문제 해결

brainstorm 10 ideas for improving user onboarding using design-thinking methodology

SCAMPER, Design Thinking 등의 프레임워크로 체계적으로 아이디어를 생성합니다.

5) 설치 및 설정

One-Line Setup

claude mcp add gemini-cli -- npx -y gemini-mcp-tool

수동 설정

{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool"]
    }
  }
}

사전 요구사항

  1. Node.js v16.0.0+
  2. Gemini CLI 설치 및 인증
# Gemini CLI 설치
npm install -g @anthropic-ai/gemini-cli

# 인증
gemini auth login

6) 대안들과의 비교

축Gemini MCP Tool직접 API 호출다른 LLM 래퍼
설정 복잡도낮음 (CLI만)중간 (API 키)높음 (SDK)
토큰 윈도우1M+모델별 상이구현별 상이
Claude 통합MCP 네이티브수동제한적
진행 알림✅구현 필요제한적
샌드박스✅별도 구현없음

마치며: 멀티모델 협업의 새로운 패턴

Gemini MCP Tool은 단순한 “API 래퍼”가 아닙니다. Claude와 Gemini의 강점을 결합하는 아키텍처 패턴입니다.

“Claude의 정교한 추론 + Gemini의 거대 컨텍스트 = 최적의 분석 조합”

특히 인상적인 점:

  1. Change Mode: Gemini의 분석을 Claude의 편집 능력과 연결
  2. Progress Notification: 긴 작업에서도 사용자 경험 유지
  3. 자동 폴백: 할당량 초과 시에도 중단 없이 동작

이 패턴은 다른 모델 조합에도 적용할 수 있습니다. MCP 서버로 각 모델의 강점을 래핑하고, Claude가 오케스트레이션하는 구조입니다.

🔗 관련 정보

# Claude Code # Gemini # MCP # Developer Tools
Compartir
이전
GitNexus: AI 에이전트를 위한 코드베이스 지식 그래프 구축
다음
CCBot: Telegram으로 Claude Code 세션을 원격 제어하는 혁신적인 접근