Gemini多模态生成MCP服务器

Claude-to-Gemini MCP Server

Claude Code에서 Google Gemini를 MCP(Model Context Protocol) 서버로 사용하는 Agent-to-Agent 통합 프로젝트

프로젝트 목적

• Claude Code: 메인 AI (일반 코딩, 디버깅, 파일 생성/수정)
• Gemini: 서브 AI (대규모 컨텍스트 분석, 코드베이스 리뷰, 이미지 생성/분석, 영상 생성, 음악 생성/오디오 분석)

주요 기능

텍스트/코드 도구

1. ask_gemini - 텍스트/코드 생성

• 용도: 일반 Gemini 호출, 큰 컨텍스트 분석
• 모델 선택:
  • flash (기본): Gemini 3.5 Flash - 빠르고 효율적
  • pro: Gemini 3.1 Pro - 고성능
  • argon: Gemini 4 Argon - 최신 플래그십, 최고 추론 성능
• 컨텍스트: 최대 1M 토큰

2. gemini_analyze_codebase - 코드베이스 분석

• 용도: 전체 코드베이스 전문 분석
• 분석 타입: architecture | duplications | security | performance | general

이미지 생성 도구

과금 안내: 모든 이미지 모델은 생성할 때마다 과금됩니다. 무료 등급은 없습니다. Google AI 가격 페이지를 확인하세요.

3. generate_logo - 로고/아이콘 생성

• 모델: Nano Banana Pro (gemini-3-pro-image)
• 특징: 전문 텍스트 렌더링, 1:1 비율, 최대 4K
• 파라미터: prompt, brandName, style, colorScheme, imageSize, thinkingLevel, searchGrounding

4. generate_illustration - 삽화/아트워크 생성

• 모델: Nano Banana 2.1 (gemini-nano-banana-2.1) 또는 Lite (gemini-3.1-flash-lite-image)
• 특징: 최대 4K, thinking 모드, Google Search/Image Search grounding
• 파라미터: prompt, style, mood, model(nb2.1/lite), aspectRatio, numberOfImages, imageSize, thinkingLevel, searchGrounding, rawPrompt
• rawPrompt: true로 설정 시 시스템 프롬프트(스타일 지시문)를 끄고 사용자 프롬프트만 전달. 픽셀아트 등 단순한 스타일에 유용.

5. generate_infographic - 인포그래픽/다이어그램 생성

• 모델: Nano Banana Pro (gemini-3-pro-image)
• 특징: 텍스트 렌더링 최적화, Google Search grounding으로 실시간 데이터 시각화
• 파라미터: prompt, data, type, aspectRatio, imageSize, thinkingLevel, searchGrounding

6. generate_photo - 사실적 사진 생성

• 모델: Nano Banana Pro (gemini-3-pro-image) — Imagen 4 지원 종료로 대체
• 특징: 포토리얼리스틱, 최대 4K, SynthID 워터마크
• 파라미터: prompt, style, numberOfImages, aspectRatio, imageSize, thinkingLevel, searchGrounding

7. generate_banner - 마케팅 배너/SNS 이미지 생성

• 모델: Nano Banana Pro (gemini-3-pro-image)
• 특징: 플랫폼별 최적 사이즈 프리셋, 텍스트+그래픽 조합
• 파라미터: prompt, text, platform, aspectRatio, imageSize, thinkingLevel, searchGrounding

8. edit_image - 이미지 편집/수정 (멀티턴)

• 모델: Nano Banana 2.1 또는 Pro (선택 가능)
• 특징:
  • 멀티턴 편집 (previousInteractionId로 이어서 수정)
  • 최대 14개 레퍼런스 이미지 (오브젝트/캐릭터/스타일)
  • Google Search + Image Search grounding
  • 최대 4K 해상도
• 파라미터: prompt, imagePath, imagePaths, action, model(nb2.1/pro), previousInteractionId, aspectRatio, imageSize, thinkingLevel, searchGrounding

이미지 분석 도구

9. analyze_image - 이미지 분석/이해

• 모델: Gemini 3.8 Flash (gemini-3.8-flash)
• 모드:
  • caption (기본): 캡셔닝, 시각 QA, 다중 이미지 비교
  • detect: 객체 감지 + 바운딩 박스 (0-1000 정규화)
  • segment: 이미지 세그멘테이션 + 폴리곤 마스크
• 지원 포맷: PNG, JPEG, WebP, HEIC, HEIF (인라인 20MB 제한)

영상 생성 도구

10. generate_video - Veo 3.1 영상 생성

• 모델: veo-3.1 (기본) | veo-3.1-fast | veo-3.1-lite
• 특징:
  • 네이티브 오디오 (대사, 효과음, 앰비언트)
  • Image-to-video, 시작+끝 프레임 보간
  • 최대 3개 레퍼런스 이미지
  • 720p / 1080p / 4K (1080p+는 8초 필수)
• 파라미터: prompt, model, aspectRatio, resolution, durationSeconds, imagePath, lastFramePath, referenceImagePaths, personGeneration

11. generate_video_omni - Gemini Omni Flash 영상 생성

• 모델: gemini-omni-1.1-flash
• 특징:
  • 대화형 멀티턴 편집/확장
  • 비디오 확장 (task: "extend")
  • 캐릭터/오브젝트 레퍼런스 이미지
  • 시작+끝 프레임 보간
  • 360p ~ 4K (720p 이상 업스케일)
• 파라미터: prompt, aspectRatio, resolution, imagePath, lastFramePath, referenceImagePaths, previousInteractionId, task

음악 생성 도구

과금 안내: Lyria 모델은 무료 등급이 없습니다. Lyria 3 Clip 약 $0.04/클립, Lyria 3.5 약 $0.08/곡 (2026-09 가격 페이지 기준). Lyria RealTime은 실험 모델이라 가격 페이지를 확인하세요.

프롬프트 가이드: MUSIC_GUIDE.md. 같은 내용을 music_prompt_guide 도구로 주제별로 볼 수 있습니다.

모든 음악 결과는 generated_music/(또는 outputDir)에 저장되고, 파일마다 .meta.json(모델, 보낸 프롬프트 전문, 인자, 생성 시각)이 붙습니다. 가사와 노래 구조가 오면 .lyrics.txt, .structure.json으로 함께 저장합니다. 생성 도구는 숨은 시스템 프롬프트 없이, 채운 필드만 덧붙이고 실제로 보낸 프롬프트를 결과에 보여 줍니다.

12. music_prompt_guide - 프롬프트 가이드 조회

• 용도: 장르·악기 키워드, 구조 태그, 가사·보컬, RealTime 조종, 게임 BGM 절차, 예시, 제한
• 특징: API 호출 없음(무료). MUSIC_GUIDE.md를 주제별로 잘라 반환
• 파라미터: topic (overview, fundamentals, genres, instruments, structure, lyrics, vocals, parameters, realtime, game_bgm, examples, limits, all)

13. generate_music_clip - 30초 음악 클립

• 모델: Lyria 3 Clip (lyria-3-clip-preview)
• 특징: 항상 30초 MP3(44.1 kHz 스테레오), 가장 빠르고 저렴. 본 생성 전 프롬프트 실험, 짧은 루프, 징글, 미리듣기
• 파라미터: prompt, genre, mood, instruments, bpm, key, instrumental, vocals, vocalLanguage, lyrics, lyricsBrief, imagePaths, outputName, outputDir

14. generate_song - 전체 길이 노래

• 모델: Lyria 3.5 (lyria-3.5)
• 특징: 수 분 길이, 절·후렴·브리지, 보컬과 가사. 직접 쓴 가사(섹션 태그) 또는 가사 방향 지시. 타임스탬프로 구간 제어. MP3 또는 WAV
• 파라미터: prompt, genre, mood, instruments, bpm, key, instrumental, vocals, vocalLanguage, lyrics, lyricsBrief, structure, timeline, durationSeconds, outputFormat, imagePaths, outputName, outputDir
• 언어: 가사는 프롬프트 언어를 따른다. 한국어 가사는 한국어 프롬프트로

15. generate_bgm - 게임·영상 배경음악

• 모델: clip(기본, 30초 MP3) 또는 full(Lyria 3.5, 기본 WAV)
• 특징: 항상 연주곡. 용도 프리셋 11종(title, exploration, battle, boss, town, shop, story, tension, ambient, victory, defeat) + custom. loop=true면 "처음부터 전체 편성, 에너지 일정, 페이드·마무리 없음" 지시를 붙이고, 결과에 다음 단계(make_loop 호출)를 안내
• 파라미터: prompt, usage, model, loop, genre, mood, instruments, bpm, key, durationSeconds, outputFormat, imagePaths, outputName, outputDir

16. generate_music_realtime - 실시간 조종 음악 녹음

• 모델: Lyria RealTime (models/lyria-realtime-exp, 실험)
• 특징: WebSocket 스트림을 정한 길이(5~600초)만큼 WAV로 녹음. 가중치 프롬프트로 장르·악기를 섞고, timeline으로 시간에 따라 바꿈(가중치를 약 1초 간격으로 보간). bpm·scale 변경 시 reset_context 자동 처리. 걸러진 프롬프트를 보고. 연주곡만
• 파라미터: prompts, durationSeconds, bpm, scale, density, brightness, guidance, temperature, topK, seed, muteBass, muteDrums, onlyBassAndDrums, mode, timeline, outputName, outputDir

17. analyze_audio - 오디오 듣고 분석

• 모델: Gemini 3.8 Flash (gemini-3.8-flash)
• 용도: Claude는 소리를 들을 수 없으므로, 생성한 음악의 확인·선택을 맡긴다
• 모드: describe(장르·BPM·조성·악기·구조), check(의도와 대조, 점수, 고친 프롬프트), loop(루프 적합성, 추천 구간), compare(2~5곡 순위), lyrics(가사 받아쓰기), custom
• 특징: 파일 헤더에서 읽은 정확한 길이를 모델에 함께 전달. 합계 약 18MB 초과 시 Files API로 자동 업로드
• 지원 포맷: MP3, WAV, AIFF, AAC, OGG, FLAC
• 파라미터: audioPaths, mode, intent, prompt

18. make_loop - 이음새 없는 루프 만들기

• 모델: 없음 (로컬 계산, 무료)
• 특징: WAV에서 루프 구간을 잘라(BPM을 주면 마디 단위) 루프 끝 다음 소리를 시작 부분에 등전력 크로스페이드. 이음새 지표(앞뒤 음량, 샘플 변화량)를 보고. previewRepeats로 두 번 이어 붙인 확인용 파일 생성
• 입력: WAV(PCM 8/16/24/32-bit, float). 출력은 16-bit WAV
• 파라미터: inputPath, startSeconds, lengthSeconds, bars, bpm, beatsPerBar, crossfadeMs, previewRepeats, outputName, outputDir

기술 스택

• Runtime: Node.js 18+
• MCP SDK: @modelcontextprotocol/sdk
• AI SDK: @google/genai (Interactions API)
• IDE: Claude Code (CLI + VSCode 확장)

설치 방법

1. 사전 준비

• Node.js 18 이상 설치
• Claude Pro/Max 플랜 구독
• Google Gemini API 키 발급 (ai.google.dev)

2. 프로젝트 클론

git clone https://github.com/YOUR_USERNAME/claude-to-gemini.git
cd claude-to-gemini

3. 의존성 설치

npm install

4. MCP 서버 등록

claude mcp add gemini \
  --env GEMINI_API_KEY=YOUR_API_KEY_HERE \
  -- node /ABSOLUTE_PATH/claude-to-gemini/index.js

주의:

• YOUR_API_KEY_HERE를 실제 Gemini API 키로 교체
• /ABSOLUTE_PATH/를 실제 프로젝트 경로로 교체

5. 확인

claude mcp list

모델 비교

텍스트/코드 모델

이미지 생성 모델

음악 생성 모델

모든 Lyria 출력에는 들리지 않는 SynthID 워터마크가 들어갑니다. 생성은 단일 턴이라 결과를 이어서 고칠 수 없습니다.

테스트

npm test

음악 도구(music.js)의 테스트입니다. fetch, WebSocket 세션, Files API를 가짜로 바꿔 끼워 실행하므로 실제 API를 부르지 않고 과금도 없습니다. 프롬프트 조립, 응답 해석, 파일 저장, WAV/MP3 헤더, RealTime 조종 계획과 녹음, 루프 이음새, 오류 메시지를 확인합니다.

보안 주의사항

API 키 보호

절대 금지: GitHub에 API 키 업로드, 코드에 하드코딩, 공개 장소에 공유

권장: 환경변수 관리, .gitignore에 .env 포함, 유출 시 즉시 재발급

.gitignore 필수 내용

node_modules/
.claude.json
.env
*.key
generated_images/
generated_videos/
generated_music/

참고 자료

• MCP 공식 문서
• Gemini API 문서
• Gemini 이미지 생성 가이드
• Gemini 가격 페이지
• Lyria 3.5 음악 생성
• Lyria RealTime
• Lyria 프롬프트 가이드
• 오디오 이해
• Claude Code 문서

라이선스

MIT License

Made with Claude Code + Gemini