MCP Gemini CrunchTools

Google Gemini AI를 위한 안전한 MCP(Model Context Protocol) 서버 - 텍스트, 이미지, 비디오, 연구 등

개요

이 MCP 서버는 다음과 같이 설계되었습니다:

• 기본 보안 - 포괄적인 위협 모델링, 입력 검증, API 키 보호

• 타사 서비스 없음 - stdio를 통해 로컬에서 실행되며 API 키가 머신을 벗어나지 않습니다

• 크로스 플랫폼 - Linux, macOS, Windows에서 작동

• 자동 업데이트 - GitHub Actions가 CVE를 모니터링하고 의존성을 업데이트

• 컨테이너화 - Hummingbird Python 기본 이미지를 기반으로 빌드된 quay.io/crunchtools/mcp-gemini에서 제공

Related MCP server: Gemini Research MCP Server

명명 규칙

왜 Hummingbird인가?

컨테이너 이미지는 Project Hummingbird의 Hummingbird Python 기본 이미지를 기반으로 빌드되었으며, 다음과 같은 이점을 제공합니다:

• 최소 CVE 노출 - Hummingbird 이미지는 최소한의 패키지 세트로 빌드되어 범용 이미지에 비해 공격 표면을 크게 줄입니다

• 정기 업데이트 - 보안 패치가 신속하게 적용되어 CVE 수를 낮게 유지합니다

• Python에 최적화 - uv 패키지 매니저가 포함된 사전 구성된 Python 환경으로 빠르고 재현 가능한 빌드를 제공합니다

• 프로덕션 준비 - 적절한 시그널 처리와 비루트 사용자 기본값을 갖춘 프로덕션 워크로드용으로 설계되었습니다

즉, MCP 서버가 일반적인 Python 컨테이너 이미지보다 취약점이 적은 강화된 환경에서 실행됩니다.

기능

쿼리 도구(5개 도구)

• gemini_query - 선택적으로 Google Search grounding을 사용하여 Gemini에 쿼리

• gemini_brainstorm - 주제에 대한 창의적인 아이디어 생성

• gemini_analyze_code - 보안, 성능, 버그 측면에서 코드 분석

• gemini_analyze_text - 감정, 어조, 내용 측면에서 텍스트 분석

• gemini_summarize - 다양한 형식으로 콘텐츠 요약

이미지 생성(4개 도구)

• gemini_generate_image - 텍스트 프롬프트에서 이미지 생성(네이티브 Gemini)

• gemini_generate_image_with_input - 기존 이미지 편집/수정

• gemini_image_prompt - 효과적인 이미지 생성 프롬프트 작성

• gemini_imagen_generate - Google Imagen 4 모델을 사용하여 이미지 생성

이미지 편집(4개 도구)

• gemini_start_image_edit - 다중 턴 이미지 편집 세션 시작

• gemini_continue_image_edit - 활성 세션에서 편집 계속

• gemini_end_image_edit - 이미지 편집 세션 종료

• gemini_list_image_sessions - 모든 활성 편집 세션 나열

이미지 분석(1개 도구)

• gemini_analyze_image - 로컬 이미지 파일 분석 및 설명

검색 도구(1개 도구)

• gemini_search - Google Search grounding을 사용하여 Gemini로 웹 검색

문서 도구(3개 도구)

• gemini_analyze_document - PDF, DOCX, TXT 등 분석

• gemini_summarize_pdf - PDF 문서 요약

• gemini_extract_tables - 문서에서 표 추출

URL 도구(3개 도구)

• gemini_analyze_url - 하나 이상의 URL 분석

• gemini_compare_urls - 두 URL 비교

• gemini_extract_from_url - URL에서 특정 데이터 추출

비디오 도구(2개 도구)

• gemini_generate_video - Veo를 사용하여 비디오 생성

• gemini_check_video - 비디오 생성 상태 확인

YouTube 도구(2개 도구)

• gemini_youtube - YouTube 비디오 분석

• gemini_youtube_summary - YouTube 비디오 요약

음성 도구(3개 도구)

• gemini_speak - 텍스트를 음성으로 변환

• gemini_dialogue - 다중 음성 대화 오디오 생성

• gemini_list_voices - 사용 가능한 음성 나열

연구 도구(3개 도구)

• gemini_deep_research - 다단계 웹 연구 수행

• gemini_check_research - 연구 작업 상태 확인

• gemini_research_followup - 후속 질문하기

캐시 도구(4개 도구)

• gemini_create_cache - 반복 쿼리를 위한 콘텐츠 캐시 생성

• gemini_query_cache - 캐시된 콘텐츠 쿼리

• gemini_list_caches - 모든 활성 캐시 나열

• gemini_delete_cache - 캐시 삭제

구조화된 출력 도구(2개 도구)

• gemini_structured - 구조화된 JSON 출력 가져오기

• gemini_extract - 텍스트에서 구조화된 데이터 추출

토큰 도구(1개 도구)

• gemini_count_tokens - 콘텐츠의 토큰 수 계산

코드 실행 도구(1개 도구)

• gemini_run_code - Gemini를 통해 Python 코드 실행

총 39개 도구

설치

uvx 사용(권장)

uvx mcp-gemini-crunchtools

pip 사용

pip install mcp-gemini-crunchtools

컨테이너 사용

# Create a shared output directory (required before first run)
mkdir -p ~/.local/share/mcp-uploads-downloads

podman run -v ~/.local/share/mcp-uploads-downloads:/output:z \
    -e GEMINI_API_KEY=your_key \
    -e GEMINI_OUTPUT_DIR=/output \
    quay.io/crunchtools/mcp-gemini

SELinux 참고: :Z(대문자, private) 대신 :z(소문자, shared)를 사용하세요. MCP 서버는 장기 실행 stdio 프로세스로 동작합니다. :Z를 사용하면 컨테이너 시작 후 디렉터리에 복사된 파일에 컨테이너의 private MCS 라벨이 없어 컨테이너 내부에서 보이지 않게 됩니다. :z 플래그는 모든 컨테이너와 호스트가 읽고 쓸 수 있는 공유 container_file_t 컨텍스트를 설정합니다.

팁: 여러 MCP 컨테이너 서버(예: mcp-gemini 및 mcp-wordpress)에서 동일한 공유 디렉터리(~/.local/share/mcp-uploads-downloads/)를 사용하면 생성된 이미지를 복사 없이 WordPress 업로드에 즉시 사용할 수 있습니다.

구성

Google Gemini API 키 만들기

1. Google AI Studio로 이동

   • https://aistudio.google.com/apikey로 이동

   • Google 계정으로 로그인

2. API 키 생성

   • "Get API key" 또는 "Create API key" 클릭

   • Google Cloud 프로젝트를 선택하거나 새로 생성

   • "Create API key in new project" 클릭(또는 기존 프로젝트 선택)

3. API 키 복사

   • 중요: API 키를 즉시 복사하세요 - 안전하게 보관하세요!

   • 키는 AI...로 시작합니다(예: AIzaSy...)

Claude Code에 추가

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    -- uvx mcp-gemini-crunchtools

또는 컨테이너 버전의 경우:

# Create a shared output directory (required before first run)
mkdir -p ~/.local/share/mcp-uploads-downloads

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    --env GEMINI_OUTPUT_DIR=/output \
    -- podman run -i --rm \
        -v ~/.local/share/mcp-uploads-downloads:/output:z \
        -e GEMINI_API_KEY \
        -e GEMINI_OUTPUT_DIR=/output \
        quay.io/crunchtools/mcp-gemini

선택 사항: 출력 디렉터리 설정(컨테이너 미사용)

컨테이너 없이 실행할 때 생성된 이미지, 오디오, 비디오의 출력 디렉터리를 설정합니다:

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    --env GEMINI_OUTPUT_DIR=$HOME/.local/share/mcp-uploads-downloads \
    -- uvx mcp-gemini-crunchtools

사용 예시

Google Search로 쿼리

User: What are the latest developments in quantum computing?
Assistant: [calls gemini_query with use_google_search=true]

이미지 생성

User: Generate a photorealistic image of a sunset over mountains
Assistant: [calls gemini_generate_image with prompt and style]

PDF 문서 분석

User: Analyze this research paper at /path/to/paper.pdf
Assistant: [calls gemini_analyze_document with file_path]

YouTube 비디오 요약

User: Summarize this YouTube video: https://youtube.com/watch?v=...
Assistant: [calls gemini_youtube_summary with url]

심층 연구

User: Research the environmental impact of electric vehicles
Assistant: [calls gemini_deep_research then gemini_check_research]

코드 분석

User: Analyze this Python code for security issues
Assistant: [calls gemini_analyze_code with focus="security"]

보안

이 서버는 보안을 최우선으로 설계되었습니다. 다음 사항은 SECURITY.md를 참조하세요:

• 위협 모델 및 공격 벡터

• 심층 방어 아키텍처

• API 키 처리 모범 사례

• 입력 검증 규칙

• 감사 로깅

주요 보안 기능

1. API 키 보호

   • SecretStr로 저장(실수로 로그에 남지 않음)

   • 환경 변수로만 제공(파일이나 인자에 절대 포함되지 않음)

   • 모든 오류 메시지에서 제거됨

2. 입력 검증

   • 모든 입력에 대한 Pydantic 모델

   • 파일 경로 검증

   • URL 검증

   • 엄격한 형식 검증

3. API 강화

   • 하드코딩된 API 기본 URL(SSRF 방지)

   • TLS 인증서 검증

   • 요청 시간 제한

   • 응답 크기 제한

4. 자동 CVE 스캐닝

   • GitHub Actions가 매주 의존성 스캔

   • 보안 업데이트를 위한 자동 PR

   • Dependabot 알림 활성화

개발

설정

git clone https://github.com/crunchtools/mcp-gemini.git
cd mcp-gemini
uv sync

테스트 실행

uv run pytest

린트 및 타입 검사

uv run ruff check src tests
uv run mypy src

컨테이너 빌드

podman build -t mcp-gemini .

라이선스

AGPL-3.0-or-later

기여

기여를 환영합니다! 보안 관련 변경 사항을 제출하기 전에 SECURITY.md를 읽어주세요.

링크

• Google Gemini API 문서

• Google AI Studio

• FastMCP 문서

• MCP 사양

• crunchtools.com