gemini-mcp

Gemini CLI를 Subprocess로 호출하는 MCP Server. Gemini Pro 구독(Google AI Pro)의 OAuth 인증을 활용하여 API Key 없이 Gemini를 사용한다.

사전 조건

• Node.js 18+
• Gemini CLI 글로벌 설치 및 OAuth 인증 완료

npm install -g @google/gemini-cli
gemini  # 최초 실행 시 OAuth 인증 진행

npx로 바로 사용

설치 없이 npx로 즉시 실행할 수 있다.

Claude Code (프로젝트별 .mcp.json 권장):

프로젝트 루트에 .mcp.json 파일을 생성한다.

{
  "mcpServers": {
    "gemini": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dongju101/gemini-mcp@latest"]
    }
  }
}

이 방식은 해당 프로젝트에서만 gemini MCP server가 기동되어 다른 세션에 영향을 주지 않는다. .mcp.json을 .gitignore에 추가하거나 팀과 공유할 수 있다.

Claude Desktop (claude_desktop_config.json):

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

Workspace 경로 override (선택):

GEMINI_MCP_HOME=/custom/path npx @dongju101/gemini-mcp@latest

버전 고정이 필요한 경우: @latest 대신 @0.2.3처럼 특정 버전을 명시할 수 있다.

버전 업데이트

npx는 전역 설치된 패키지를 우선 사용하므로, 구버전이 전역에 설치되어 있으면 새 버전이 반영되지 않는다.

# 전역 설치 업데이트
npm install -g @dongju101/gemini-mcp@latest

# npx 캐시 삭제 (전역 설치 없이 npx 캐시만 사용하는 경우)
rm -rf ~/.npm/_npx

업데이트 후 Claude Code에서 MCP 서버를 재시작한다.

기본 Workspace는 프로젝트 루트의 .gemini-mcp/에 자동 생성된다. .gitignore에 .gemini-mcp/를 추가하여 커밋에서 제외한다.

기존 ~/.gemini-mcp/ 사용자 마이그레이션:

이전 버전을 사용 중이었다면, ~/.gemini-mcp/에 session 데이터가 남아 있을 수 있다. 필요한 데이터를 프로젝트 루트의 .gemini-mcp/로 복사하거나 삭제한다.

# 이전 데이터 제거 (선택)
rm -rf ~/.gemini-mcp/

소스에서 설치

git clone https://github.com/DvwN-Lee/gemini_mcp.git
cd gemini_mcp
npm install
npm run build

프로젝트 루트에 .mcp.json을 생성한다.

{
  "mcpServers": {
    "gemini": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/gemini_mcp/dist/server.js"]
    }
  }
}

설정

.gemini-mcp/config.json으로 Server 동작을 제어한다. Config 파일이 없거나 잘못된 경우 각 항목의 기본값이 적용된다.

{
  "file_access": true,
  "model": "gemini-3-pro-preview",
  "system_prompt": "You are a concise technical assistant.",
  "timeout": 300,
  "total_timeout": 600
}

파일 접근 (file_access)

Gemini가 프로젝트 파일에 접근할 수 있는지를 제어한다.

값	동작
true (기본값)	Project Root에서 실행. Gemini가 프로젝트 파일을 읽고 분석 가능.
false	격리된 Workspace에서 실행. 프로젝트 파일 접근 불가.

Model 선택 (model)

Gemini CLI에서 사용할 Model을 지정한다.

값	동작
미지정 (기본값)	auto mode -- Gemini가 최적 모델을 자동 선택
"gemini-3.1-pro-preview"	최신 모델. 복잡한 추론, agentic workflow, 1M context
"gemini-3-pro-preview"	복잡한 추론, 코드 분석, 아키텍처 설계
"gemini-3-flash-preview"	단순 질의, 번역, 요약 등 빠른 응답이 우선인 작업
"gemini-2.5-pro" / "gemini-2.5-flash"	3 계열 모델이 quota 초과 또는 오류 시 대체

Tool 호출 시 model Parameter를 직접 지정하면 Config 설정보다 우선 적용된다.

Timeout 설정 (timeout / total_timeout)

Gemini CLI 응답 대기 시간을 제어한다.

값	동작
timeout	줄 단위 응답 대기 시간(초). 이 시간 동안 출력이 없으면 타임아웃. 기본값: 300
total_timeout	전체 요청 최대 허용 시간(초). 기본값: 600

복잡한 코드베이스 분석처럼 긴 요청은 Gemini API의 첫 응답까지 수 분이 걸릴 수 있다. 필요 시 값을 늘린다.

시스템 프롬프트 (system_prompt)

Gemini에게 전달할 기본 시스템 프롬프트를 지정한다.

값	동작
미지정 (기본값)	내장 기본 프롬프트 사용 (간결한 기술 어시스턴트 페르소나)
"<문자열>"	지정한 문자열을 시스템 프롬프트로 사용

Session 디렉토리의 GEMINI.md에 기록되어 Gemini CLI에 전달된다. file_access: true이면 프로젝트 루트 경로 및 파일 읽기 지시도 자동으로 추가된다.

설정 예시

# 기본 모델 + 파일 접근 활성화
echo '{"file_access": true}' > .gemini-mcp/config.json

# 특정 Model 고정 + 파일 접근 활성화
echo '{"file_access": true, "model": "gemini-3-flash-preview"}' > .gemini-mcp/config.json

Tool 목록

Tool	Parameter	용도
gemini_chat	message, model, session, sandbox, change_mode, include_meta	Gemini와 대화형 질의. --resume으로 이전 대화 맥락 자동 유지.
gemini_reset	session	대화 Session 초기화. 다음 호출부터 새 대화 시작.
gemini_fetch_chunk	cache_key, chunk_index	change_mode 응답이 여러 chunk로 분할된 경우 후속 chunk 조회.

gemini_chat Parameter

Parameter	기본값	설명
message	(필수)	Gemini에 전달할 메시지
model	"" (auto)	사용할 모델. 빈 문자열이면 Gemini가 최적 모델을 자동 선택
session	"default"	Session 이름. 독립적인 대화 맥락 유지
sandbox	false	Sandbox mode로 code를 격리 환경에서 실행
change_mode	false	코드 수정 요청 시 활성화. 응답을 구조화된 OLD/NEW 포맷으로 파싱하여 Edit tool 적용 가능.
include_meta	false	true 시 응답 footer에 사용 model명과 token 수를 표시. change_mode와 함께 사용 시 아래 제약사항 참고.

include_meta + change_mode 결합 시 동작: change_mode: true와 include_meta: true를 동시에 사용하는 경우, 파싱 성공/실패와 관계없이 meta footer(model명, token 수)가 응답 끝에 포함된다. 파싱 성공 시 구조화된 편집 결과 뒤에, 파싱 실패 시 원본 응답 뒤에 footer가 추가된다.

Multi-Session

여러 Terminal에서 독립적인 대화를 유지할 수 있다. session Parameter로 Session 이름을 지정하면 각각의 대화 맥락이 격리된다.

Terminal A (frontend 작업):
  gemini_chat(message="React Component 구조 설명해줘", session="frontend")
  gemini_chat(message="위 구조에서 상태 관리는?", session="frontend")  -> 이전 맥락 유지

Terminal B (backend 작업):
  gemini_chat(message="Express Router 패턴 알려줘", session="backend")
  gemini_chat(message="위 패턴에 인증 추가하려면?", session="backend")  -> 독립적 맥락 유지

• session 미지정 시 "default" Session 사용
• Session별 Workspace가 .gemini-mcp/sessions/{session_name}/에 자동 생성
• Claude Code를 종료했다 재시작해도 --resume으로 직전 대화를 이어갈 수 있다
• gemini_reset(session="frontend"): 특정 Session만 초기화
• gemini_reset(): 전체 Session 초기화

디렉토리 구조

gemini_mcp/                  # 소스 Repository
  src/
    server.ts                # FastMCP Server 진입점 · Tool/Prompt/Resource 정의
    runner.ts                # Gemini CLI Subprocess 실행기
    workspace.ts             # Workspace 파일시스템 관리
    changeMode.ts            # change_mode 응답 파서 및 chunk 캐시
    progress.ts              # ProgressTracker (MCP notifications/progress)
    util.ts                  # 공통 유틸리티
    types.ts                 # Type 정의 (GeminiResponse, RunnerEvent 등)
    __tests__/               # Vitest 테스트
  dist/                      # TypeScript 빌드 출력
  docs/                      # 기술 문서
  package.json
  tsconfig.json
  vitest.config.ts

.gemini-mcp/                 # Runtime Workspace (프로젝트 루트에 자동 생성)
  config.json                # Server 설정 (file_access, model, system_prompt)
  .gemini/
    settings.json            # CLI 설정 (mcpServers: {}, security.auth)
  sessions/                  # Session별 독립 Workspace

테스트

npm test            # Vitest 실행
npm run test:watch  # Watch mode

기술 문서

• 전략 분석 -- 5개 접근 전략 비교 및 선정 근거
• 기술 조사 -- CLI 동작 분석, stream-json 구조, Cold Start 분석
• Architecture -- 시스템 구조, 데이터 흐름, 구현 설계
• 성능 분석 -- Token 소비 및 Latency 최적화 분석
• 정책 준수 분석 -- Gemini ToS 및 사용 정책 준수 분석
• Gemini 출력 분석 -- stream-json 출력 포맷 분석
• 세션 리셋 분석 -- Session 초기화 동작 분석