MCP Gemini CrunchTools
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 저장소 | |
컨테이너 |
|
Python 패키지(PyPI) |
|
CLI 명령어 |
|
모듈 임포트 |
|
왜 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-crunchtoolspip 사용
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-geminiSELinux 참고:
: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 키 만들기
Google AI Studio로 이동
Google 계정으로 로그인
API 키 생성
"Get API key" 또는 "Create API key" 클릭
Google Cloud 프로젝트를 선택하거나 새로 생성
"Create API key in new project" 클릭(또는 기존 프로젝트 선택)
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 키 처리 모범 사례
입력 검증 규칙
감사 로깅
주요 보안 기능
API 키 보호
SecretStr로 저장(실수로 로그에 남지 않음)
환경 변수로만 제공(파일이나 인자에 절대 포함되지 않음)
모든 오류 메시지에서 제거됨
입력 검증
모든 입력에 대한 Pydantic 모델
파일 경로 검증
URL 검증
엄격한 형식 검증
API 강화
하드코딩된 API 기본 URL(SSRF 방지)
TLS 인증서 검증
요청 시간 제한
응답 크기 제한
자동 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 toolsgemini_analyze_code_toolGemini Analyze Code ToolCRead-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 ToolCRead-only
Analyze and describe a local image file.
Inputs: image_path (required), model, query. Returns: object
gemini_analyze_text_toolGemini Analyze Text ToolCRead-only
Analyze text with Gemini.
Inputs: text (required), model, analysis_type. Returns: object
gemini_analyze_url_toolGemini Analyze Url ToolCRead-only
Analyze one or more URLs.
Inputs: urls (required), model, question, use_google_search. Returns: object
gemini_brainstorm_toolGemini Brainstorm ToolCRead-only
Brainstorm ideas on a topic using Gemini.
Inputs: topic (required), model, context, num_ideas. Returns: object
gemini_check_research_toolGemini Check Research ToolCRead-only
Check the status of a deep research operation.
Inputs: research_id (required). Returns: object
gemini_check_video_toolGemini Check Video ToolBRead-only
Check the status of a video generation operation.
Inputs: operation_name (required). Returns: object
gemini_compare_urls_toolGemini Compare Urls ToolCRead-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 ToolBRead-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 ToolCRead-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 ToolCRead-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 ToolCRead-only
Help craft an effective image generation prompt.
Inputs: description (required), mood, model, style. Returns: object
gemini_list_caches_toolGemini List Caches ToolBRead-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 ToolARead-only
List available voices for text-to-speech.
Inputs: no named parameters. Returns: object
gemini_query_cache_toolGemini Query Cache ToolCRead-only
Query content in a cache.
Inputs: question (required), cache_name (required). Returns: object
gemini_query_toolGemini Query ToolCRead-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 ToolBRead-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 ToolBRead-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 ToolCRead-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 ToolCRead-only
Summarize content with Gemini.
Inputs: content (required), model, format, length. Returns: object
gemini_youtube_summary_toolGemini Youtube Summary ToolCRead-only
Summarize a YouTube video.
Inputs: url (required), model, style. Returns: object
gemini_youtube_toolGemini Youtube ToolCRead-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
Scored across 39 tools
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.
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.
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.
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
Related MCP Connectors
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Google Veo AI video generation
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceA dedicated server that wraps Google's Gemini AI models in a Model Context Protocol (MCP) interface, allowing other LLMs and MCP-compatible systems to access Gemini's capabilities like content generation, function calling, chat, and file handling through standardized tools.1636MIT
- AlicenseAqualityBmaintenanceMCP server for AI-powered research using Gemini. Provides fast grounded web search, deep autonomous research, URL extraction, and session management.988 PyPI10MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Google Gemini that does not require an API key, combining a CLI backend for Q\&A, research, and analysis with a web UI backend for image and video generation.4 npm3MIT
- AlicenseAqualityCmaintenanceMCP server for Google's Gemini API, enabling text, image, video, speech, embeddings, and deep research capabilities through a single tool set.10MIT