# Gemini MCP Server PRD
## 개요
Claude Code에서 Google Gemini AI 기능을 범용으로 사용하기 위한 MCP(Model Context Protocol) 서버
### 목표
- PDF, 이미지, 텍스트, 코드 분석을 위한 통합 MCP 도구 제공
- Claude Code 환경에서 Gemini의 멀티모달 기능 활용
- Gemini CLI 연동으로 높은 쿼터 지원 (Google One 구독자)
- 세션 기반 멀티턴 대화 지원
### 배경
- `stock_research` 프로젝트에서 PDF 분석 기능 검증 완료
- Gemini 3 시리즈의 강력한 멀티모달 능력 활용
- CLI 백엔드로 Free Tier 대비 50배 높은 쿼터 제공
---
## 기술 스택
| 구분 | 기술 |
|------|------|
| 런타임 | Node.js 18+ |
| 언어 | TypeScript 5.x |
| MCP SDK | @modelcontextprotocol/sdk |
| AI SDK | @google/genai |
| CLI | Gemini CLI (google-gemini/gemini-cli) |
| 기본 모델 | gemini-3-flash-preview |
| HTTP 클라이언트 | axios |
---
## 백엔드 비교
### API vs CLI
| 백엔드 | RPM | RPD | 기본 모델 | 설명 |
|--------|-----|-----|----------|------|
| `cli` (기본) | 60 | 1,000 | gemini-3-flash-preview | Gemini CLI 사용 |
| `api` | 5 | 20 | gemini-3-flash-preview | 직접 API 호출 |
### CLI 자동 감지
- Gemini CLI가 설치되어 있으면 자동으로 CLI 백엔드 사용
- CLI 미설치 시 API 백엔드로 폴백
- `provider` 파라미터로 수동 선택 가능
### Google One 구독자
- CLI 사용 시 더 높은 쿼터 자동 적용
- Google 계정 로그인으로 자동 인증
---
## 모델 선택
| 파라미터 | 모델 ID | 설명 |
|----------|---------|------|
| `flash` (기본) | gemini-3-flash-preview | 최신, 가장 빠름 |
| `pro` | gemini-3-pro-preview | 최신, 복잡한 추론 |
| `flash-2.5` | gemini-2.5-flash | 레거시 |
| `pro-2.5` | gemini-2.5-pro | 레거시 |
| `flash-lite` | gemini-2.5-flash-lite | 저비용/대량 처리 |
---
## MCP 도구 명세
### 공통 파라미터
모든 도구에 다음 파라미터 지원:
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| model | string | X | 모델 선택 (flash/pro/flash-2.5/pro-2.5/flash-lite) |
| provider | string | X | 백엔드 선택 (api/cli, 기본: 자동 감지) |
### 1. analyze_pdf
PDF 문서 분석 도구 (표, 차트, 이미지 포함)
#### 입력 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| source | string | O | PDF 경로 (URL 또는 로컬 파일) |
| prompt | string | O | 분석 프롬프트 |
#### 출력
```json
{
"success": true,
"analysis": "분석 결과 텍스트",
"model": "gemini-3-flash-preview",
"provider": "cli",
"source": "https://example.com/doc.pdf",
"sourceType": "url",
"fileSizeBytes": 1234567,
"tokenUsage": {
"promptTokens": 1000,
"completionTokens": 500,
"totalTokens": 1500
}
}
```
#### 사용 예시
```
analyze_pdf(
source: "~/documents/report.pdf",
prompt: "이 보고서의 핵심 내용을 3가지로 요약해주세요"
)
```
---
### 2. analyze_image
이미지 분석 도구 (스크린샷, 차트, 다이어그램, 사진)
#### 입력 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| source | string | O | 이미지 경로 (URL 또는 로컬 파일) |
| prompt | string | O | 분석 프롬프트 |
#### 지원 포맷
- JPEG, PNG, GIF, WebP
- 최대 파일 크기: 20MB
#### 사용 예시
```
analyze_image(
source: "~/screenshots/error.png",
prompt: "이 스크린샷에서 에러 메시지를 분석해주세요"
)
```
---
### 3. generate_text
텍스트 생성/요약/번역 도구
#### 입력 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| prompt | string | O | 생성 프롬프트 |
| context | string | X | 추가 컨텍스트 |
| maxTokens | number | X | 최대 출력 토큰 (기본: 8192) |
#### 사용 예시
```
generate_text(
prompt: "다음 텍스트를 영어로 번역해주세요",
context: "안녕하세요, 반갑습니다.",
provider: "cli"
)
```
---
### 4. analyze_code
코드 리뷰/설명 도구
#### 입력 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| code | string | O | 분석할 코드 |
| language | string | X | 프로그래밍 언어 |
| task | string | X | 분석 유형 (review/explain/improve, 기본: review) |
| prompt | string | X | 커스텀 프롬프트 |
#### 분석 유형
| 유형 | 설명 |
|------|------|
| review | 코드 리뷰 (버그, 보안, 성능) |
| explain | 코드 설명 |
| improve | 개선 제안 |
#### 사용 예시
```
analyze_code(
code: "function add(a, b) { return a + b; }",
language: "javascript",
task: "review"
)
```
---
### 5. gemini_chat (CLI 전용)
세션 기반 멀티턴 대화 도구
#### 입력 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|----------|------|------|------|
| message | string | O | 대화 메시지 |
| resume | string/number | X | 세션 재개 ("latest" 또는 세션 인덱스) |
| model | string | X | 모델 선택 |
#### 사용 예시
```
# 새 대화 시작
gemini_chat(message: "이 코드 리뷰해줘")
# 이전 대화 이어가기
gemini_chat(message: "더 자세히 설명해줘", resume: "latest")
# 특정 세션 재개
gemini_chat(message: "계속해서...", resume: 1)
```
---
### 6. gemini_sessions (CLI 전용)
대화 세션 목록 조회 도구
#### 출력
```json
{
"success": true,
"sessions": [
{
"index": 1,
"title": "코드 리뷰 토론",
"timeAgo": "5 minutes ago",
"sessionId": "abc-123-def"
}
],
"count": 1
}
```
---
## 로깅
### 환경 변수
| 변수 | 기본값 | 설명 |
|------|--------|------|
| GEMINI_LOG_LEVEL | info | 로그 레벨 (debug, info, warn, error, none) |
| GEMINI_LOG_DIR | ~/.gemini-mcp/logs | 로그 디렉토리 |
| GEMINI_LOG_FILE | - | 커스텀 로그 파일 경로 |
### 로그 파일
- `gemini-mcp-YYYY-MM-DD.log` - 전체 로그
- `gemini-mcp-YYYY-MM-DD-error.log` - 에러 로그
### 로그 항목
| 필드 | 설명 |
|------|------|
| timestamp | ISO 형식 타임스탬프 |
| type | request / response |
| tool | 도구 이름 |
| provider | api / cli |
| model | 모델 ID |
| prompt | 요청 프롬프트 |
| response | 응답 텍스트 |
| tokenUsage | 토큰 사용량 |
| durationMs | 소요 시간 |
| error | 에러 메시지 (실패 시) |
---
## 프로젝트 구조
```
gemini-mcp/
├── docs/
│ └── PRD.md
├── src/
│ ├── index.ts # MCP 서버 진입점
│ ├── tools/
│ │ ├── analyze-pdf.ts
│ │ ├── analyze-image.ts
│ │ ├── generate-text.ts
│ │ ├── analyze-code.ts
│ │ └── gemini-chat.ts # 세션 기반 대화
│ └── services/
│ ├── gemini.ts # 통합 Gemini 서비스
│ ├── gemini-cli.ts # CLI 백엔드
│ └── logger.ts # 로깅 서비스
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md
```
---
## 환경 설정
### Gemini CLI 설치 (권장)
```bash
npm install -g @google/gemini-cli
gemini # 첫 실행 시 Google 계정 로그인
```
### Claude Code MCP 설정 (~/.mcp.json)
```json
{
"mcpServers": {
"gemini": {
"command": "node",
"args": ["/path/to/gemini-mcp/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key",
"GEMINI_LOG_LEVEL": "info"
}
}
}
}
```
> API 키는 CLI 사용 시 선택사항입니다.
---
## 에러 처리
| 에러 코드 | 설명 | 대응 |
|-----------|------|------|
| RESOURCE_EXHAUSTED | API 요청 한도 초과 | CLI로 전환 또는 잠시 후 재시도 |
| INVALID_ARGUMENT | 잘못된 파일 형식 | 파일 확인 |
| PERMISSION_DENIED | API 키 오류 | API 키 확인 또는 CLI 로그인 |
| FILE_NOT_FOUND | 파일 없음 | 경로 확인 |
| CLI_NOT_AVAILABLE | CLI 미설치 | Gemini CLI 설치 |
---
## 개발 일정
| 단계 | 작업 | 상태 |
|------|------|------|
| 1 | PRD 작성 | ✅ 완료 |
| 2 | 프로젝트 초기화 | ✅ 완료 |
| 3 | Gemini API 서비스 구현 | ✅ 완료 |
| 4 | MCP 도구 구현 | ✅ 완료 |
| 5 | Gemini CLI 백엔드 추가 | ✅ 완료 |
| 6 | 로깅 기능 추가 | ✅ 완료 |
| 7 | 세션 기반 대화 기능 | ✅ 완료 |
| 8 | Gemini 3 모델 업그레이드 | ✅ 완료 |
| 9 | GitHub 배포 | ✅ 완료 |
---
## 참고 자료
- [Gemini API 모델](https://ai.google.dev/gemini-api/docs/models)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
- [Gemini API 쿼터](https://ai.google.dev/gemini-api/docs/rate-limits)
- [MCP SDK 문서](https://modelcontextprotocol.io)
- [@google/genai 패키지](https://www.npmjs.com/package/@google/genai)
