Skip to main content
Glama

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

명명 규칙

구성 요소

이름

GitHub 저장소

crunchtools/mcp-gemini

컨테이너

quay.io/crunchtools/mcp-gemini

Python 패키지(PyPI)

mcp-gemini-crunchtools

CLI 명령어

mcp-gemini-crunchtools

모듈 임포트

mcp_gemini_crunchtools

왜 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로 이동

  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

사용 예시

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를 읽어주세요.

링크

Available Tools

39 tools
gemini_analyze_code_toolGemini Analyze Code ToolC
Read-only

Analyze code with Gemini.

Inputs: code (required), focus, model, language. Returns: object

gemini_analyze_document_toolGemini Analyze Document ToolC

Analyze a document (PDF, DOCX, TXT, etc.).

Inputs: file_path (required), model, question. Returns: object

gemini_analyze_image_toolGemini Analyze Image ToolC
Read-only

Analyze and describe a local image file.

Inputs: image_path (required), model, query. Returns: object

gemini_analyze_text_toolGemini Analyze Text ToolC
Read-only

Analyze text with Gemini.

Inputs: text (required), model, analysis_type. Returns: object

gemini_analyze_url_toolGemini Analyze Url ToolC
Read-only

Analyze one or more URLs.

Inputs: urls (required), model, question, use_google_search. Returns: object

gemini_brainstorm_toolGemini Brainstorm ToolC
Read-only

Brainstorm ideas on a topic using Gemini.

Inputs: topic (required), model, context, num_ideas. Returns: object

gemini_check_research_toolGemini Check Research ToolC
Read-only

Check the status of a deep research operation.

Inputs: research_id (required). Returns: object

gemini_check_video_toolGemini Check Video ToolB
Read-only

Check the status of a video generation operation.

Inputs: operation_name (required). Returns: object

gemini_compare_urls_toolGemini Compare Urls ToolC
Read-only

Compare two URLs.

Inputs: url1 (required), url2 (required), model, aspect. Returns: object

gemini_continue_image_edit_toolGemini Continue Image Edit ToolC

Continue editing in an active image session.

Inputs: prompt (required), session_id (required). Returns: object

gemini_count_tokens_toolGemini Count Tokens ToolB
Read-only

Count the number of tokens in content.

Inputs: content (required), model. Returns: object

gemini_create_cache_toolGemini Create Cache ToolB

Create a content cache for repeated queries.

Upload content once and query it multiple times without re-sending.

Inputs: model, content, file_path, ttl_minutes, +2 more. Returns: object

gemini_deep_research_toolGemini Deep Research ToolB

Start a deep research task using a specialized Gemini model.

Performs multi-step web research to answer complex questions. Completes in a single call; the result is returned immediately.

Inputs: query (required). Returns: object

gemini_delete_cache_toolGemini Delete Cache ToolC

Delete a content cache.

Inputs: cache_name (required). Returns: object

gemini_dialogue_toolGemini Dialogue ToolC

Generate multi-voice dialogue audio.

Inputs: text (required), voice1, voice2. Returns: object

gemini_end_image_edit_toolGemini End Image Edit ToolB

End an image editing session and free resources.

Inputs: session_id (required). Returns: object

gemini_extract_from_url_toolGemini Extract From Url ToolC
Read-only

Extract specific data from a URL.

Inputs: url (required), model, data_type, custom_fields. Returns: object

gemini_extract_tables_toolGemini Extract Tables ToolC

Extract tables from a document.

Inputs: file_path (required), model, output_format. Returns: object

gemini_extract_toolGemini Extract ToolC
Read-only

Extract structured data from text.

Inputs: text (required), model, extract_type, custom_fields. Returns: object

gemini_generate_image_toolGemini Generate Image ToolB

Generate an image from a text prompt using Gemini's native image model.

Inputs: prompt (required), style, image_size, aspect_ratio, +1 more. Returns: object

gemini_generate_image_with_input_toolGemini Generate Image With Input ToolA

Generate/edit an image using a local image file as input.

Upload a local image and give Gemini instructions for how to modify it. Use cases: add watermarks, change styles, composite images, etc.

Inputs: prompt (required), file_path (required), _aspect_ratio. Returns: object

gemini_generate_video_toolGemini Generate Video ToolB

Generate a video using Veo. Returns an operation ID to poll.

Inputs: prompt (required), _aspect_ratio, negative_prompt. Returns: object

gemini_imagen_generate_toolGemini Imagen Generate ToolA

Generate images using Google Imagen 4 models.

Models (sorted by price):

  • imagen-4.0-fast-generate-001 ($0.02/image, fastest)

  • imagen-4.0-generate-001 ($0.04/image, standard)

  • imagen-4.0-ultra-generate-001 ($0.06/image, highest quality)

Inputs: prompt (required), model, aspect_ratio, number_of_images. Returns: object

gemini_image_prompt_toolGemini Image Prompt ToolC
Read-only

Help craft an effective image generation prompt.

Inputs: description (required), mood, model, style. Returns: object

gemini_list_caches_toolGemini List Caches ToolB
Read-only

List all active content caches.

Inputs: no named parameters. Returns: object

gemini_list_image_sessions_toolGemini List Image Sessions ToolB

List all active image editing sessions.

Inputs: no named parameters. Returns: object

gemini_list_voices_toolGemini List Voices ToolA
Read-only

List available voices for text-to-speech.

Inputs: no named parameters. Returns: object

gemini_query_cache_toolGemini Query Cache ToolC
Read-only

Query content in a cache.

Inputs: question (required), cache_name (required). Returns: object

gemini_query_toolGemini Query ToolC
Read-only

Query Gemini with a prompt. Supports Google Search grounding.

Inputs: prompt (required), model, use_google_search, system_instruction. Returns: object

gemini_research_followup_toolGemini Research Followup ToolB
Read-only

Ask a follow-up question about completed research.

Inputs: question (required), research_id (required). Returns: object

gemini_run_code_toolGemini Run Code ToolB

Execute code using Gemini's built-in code execution.

Gemini writes and runs Python code to answer questions, perform calculations, or process data.

Inputs: prompt (required), data, model. Returns: object

gemini_search_toolGemini Search ToolB
Read-only

Search the web using Gemini with Google Search grounding.

Inputs: query (required), model. Returns: object

gemini_speak_toolGemini Speak ToolC

Convert text to speech.

Inputs: text (required), voice. Returns: object

gemini_start_image_edit_toolGemini Start Image Edit ToolA

Start a multi-turn image editing session.

Optionally provide an existing image file as the starting point. Without file_path, Gemini generates a new image from the prompt. Use gemini_continue_image_edit_tool to make further edits.

Inputs: prompt (required), file_path, use_google_search. Returns: object

gemini_structured_toolGemini Structured ToolC
Read-only

Get structured JSON output from Gemini.

Inputs: prompt (required), model, schema, use_google_search. Returns: object

gemini_summarize_pdf_toolGemini Summarize Pdf ToolC

Summarize a PDF document.

Inputs: file_path (required), model, style. Returns: object

gemini_summarize_toolGemini Summarize ToolC
Read-only

Summarize content with Gemini.

Inputs: content (required), model, format, length. Returns: object

gemini_youtube_summary_toolGemini Youtube Summary ToolC
Read-only

Summarize a YouTube video.

Inputs: url (required), model, style. Returns: object

gemini_youtube_toolGemini Youtube ToolC
Read-only

Analyze a YouTube video.

Inputs: url (required), model, question. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 39 tools

    Disambiguation2/5

    Many tools overlap: multiple image generation/editing tools (gemini_generate_image_tool, gemini_imagen_generate_tool, gemini_generate_image_with_input_tool, gemini_start_image_edit_tool), multiple document analysis tools (analyze_document, summarize_pdf, extract_tables), multiple URL tools (analyze_url, compare_urls, extract_from_url), and general query/analyze/summarize/brainstorm tools. Descriptions help but boundaries are fuzzy, risking misselection.

    Naming Consistency4/5

    All tools use snake_case with a consistent 'gemini_' prefix and '_tool' suffix. However, some names lack an action verb (gemini_youtube_tool, gemini_dialogue_tool, gemini_structured_tool) and word order varies (gemini_imagen_generate_tool vs gemini_generate_image_tool), preventing a perfect score.

    Tool Count2/5

    39 tools is well above the recommended 3-15 range and exceeds the 25-tool threshold for 'too many.' While the server covers many modalities, the count suggests redundant or overly granular tooling that could be consolidated.

    Completeness4/5

    The toolset covers a wide range of Gemini capabilities: image/video/audio generation, document/URL/YouTube analysis, research, caching, structured output, token counting, and code execution. Minor gaps exist (e.g., no speech-to-text, no model listing, no embedding generation), but core workflows are well supported.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers