README.md

🇰🇷 Advanced Gemini MCP Server v4.0 - Korean Open Source Edition

"We hope this helps the global developer community!"
"전 세계 개발자 커뮤니티에 도움이 되길 바랍니다!"

---

📋 Table of Contents | 목차

• English
  • Overview
  • Features
  • Installation
  • Usage
  • Configuration
  • Examples
  • API Reference
  • Contributing
  • License
• 한국어
  • 개요
  • 주요 기능
  • 설치 방법
  • 사용법
  • 설정
  • 사용 예제
  • API 참조
  • 기여하기
  • 라이선스

---

English

Overview

The Advanced Gemini MCP Server v4.0 is a comprehensive Model Context Protocol (MCP) server implementation that provides seamless integration with Google's Gemini AI. This open-source project was developed with ❤️ in South Korea to contribute to the global developer community.

👨‍💻 Authors

• 삽질싼타 (Sapjil Santa) - Lead Developer
• 이하늬 (Lee Haneui) - AI Assistant & Co-Developer
• Contact: codenmsanta@gmail.com

Features

🚀 10 Advanced AI Capabilities

1. Text Generation - Basic text generation with customizable parameters
2. Multimodal Processing - Support for images, videos, and audio files
3. Token Counting - Accurate token counting for cost estimation
4. Streaming Response - Real-time streaming for long responses
5. Structured JSON Output - Schema-enforced JSON generation
6. System Instructions - Custom AI behavior with system prompts
7. Function Calling - Dynamic function execution capabilities
8. Code Execution - Safe Python code execution with AI
9. File Upload & Analysis - Upload and analyze various file formats
10. Grounded Search - Real-time web search integration

🔧 Technical Features

• Production Ready: Comprehensive error handling and logging
• Security First: Environment variable API key management
• Korean + English: Bilingual documentation and error messages
• MCP Compatible: Full compliance with Model Context Protocol
• Async Support: Modern asyncio-based architecture
• Type Safety: Full type hints for better development experience

Installation

Prerequisites

• Python 3.8 or higher
• Google Gemini API key
• pip package manager

Quick Install

# Clone the repository
git clone https://github.com/SapjilSanta/advanced-gemini-mcp.git
cd advanced-gemini-mcp

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
export GEMINI_API_KEY="your-gemini-api-key-here"

Package Dependencies

google-genai>=0.7.0
mcp>=1.0.0
asyncio
aiofiles
typing-extensions

Usage

Basic Setup

1. Set your API key:

   export GEMINI_API_KEY="your-api-key"
   

2. Run the server:

   python advanced_gemini_mcp.py
   

3. Connect your MCP client and start using the 10 available tools!

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "advanced-gemini": {
      "command": "python",
      "args": ["/path/to/advanced_gemini_mcp.py"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini API key

Customization

The server supports various configuration options through tool parameters:

• Temperature: Control creativity (0.0-1.0)
• Max Tokens: Limit response length
• Model Selection: Choose specific Gemini models
• File Types: Support for multiple media formats

Examples

Text Generation

# Tool: gemini_generate
{
  "prompt": "Explain quantum computing in simple terms",
  "temperature": 0.7,
  "max_tokens": 1000
}

Image Analysis

# Tool: gemini_multimodal
{
  "prompt": "Describe what you see in this image",
  "image_path": "/path/to/image.jpg"
}

Code Execution

# Tool: gemini_code_execution
{
  "prompt": "Calculate the fibonacci sequence up to 10 numbers and plot it"
}

API Reference

For detailed API documentation, see API_REFERENCE.md.

Contributing

We welcome contributions from developers worldwide! 🌍

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Coding Standards

• Follow PEP 8 style guidelines
• Add type hints to all functions
• Include docstrings for public APIs
• Write comprehensive error handling

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

한국어

개요

고급 제미나이 MCP 서버 v4.0은 구글의 제미나이 AI와 원활한 통합을 제공하는 포괄적인 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. 이 오픈소스 프로젝트는 전 세계 개발자 커뮤니티에 기여하기 위해 대한민국에서 ❤️를 담아 개발되었습니다.

👨‍💻 제작자

• 삽질싼타 - 주개발자
• 이하늬 - AI 어시스턴트 & 공동개발자
• 연락처: codenmsanta@gmail.com

주요 기능

🚀 10가지 고급 AI 기능

1. 텍스트 생성 - 맞춤 설정 가능한 기본 텍스트 생성
2. 멀티모달 처리 - 이미지, 동영상, 오디오 파일 지원
3. 토큰 계산 - 비용 추정을 위한 정확한 토큰 계산
4. 스트리밍 응답 - 긴 응답을 위한 실시간 스트리밍
5. 구조화된 JSON 출력 - 스키마 강제 JSON 생성
6. 시스템 지시사항 - 시스템 프롬프트로 AI 행동 커스터마이징
7. 함수 호출 - 동적 함수 실행 기능
8. 코드 실행 - AI와 함께하는 안전한 파이썬 코드 실행
9. 파일 업로드 및 분석 - 다양한 파일 형식 업로드 및 분석
10. 근거 기반 검색 - 실시간 웹 검색 통합

🔧 기술적 특징

• 프로덕션 준비: 포괄적인 오류 처리 및 로깅
• 보안 우선: 환경 변수 API 키 관리
• 한국어 + 영어: 이중 언어 문서화 및 오류 메시지
• MCP 호환: 모델 컨텍스트 프로토콜 완전 준수
• 비동기 지원: 최신 asyncio 기반 아키텍처
• 타입 안전성: 더 나은 개발 경험을 위한 완전한 타입 힌트

설치 방법

필수 조건

• Python 3.8 이상
• Google Gemini API 키
• pip 패키지 매니저

빠른 설치

# 저장소 복제
git clone https://github.com/SapjilSanta/advanced-gemini-mcp.git
cd advanced-gemini-mcp

# 의존성 설치
pip install -r requirements.txt

# 환경 변수 설정
export GEMINI_API_KEY="your-gemini-api-key-here"

패키지 의존성

google-genai>=0.7.0
mcp>=1.0.0
asyncio
aiofiles
typing-extensions

사용법

기본 설정

1. API 키 설정:

   export GEMINI_API_KEY="your-api-key"
   

2. 서버 실행:

   python advanced_gemini_mcp.py
   

3. MCP 클라이언트 연결 후 10가지 도구 사용 시작!

MCP 클라이언트 설정

MCP 클라이언트 설정에 추가:

{
  "mcpServers": {
    "advanced-gemini": {
      "command": "python",
      "args": ["/path/to/advanced_gemini_mcp.py"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

설정

환경 변수

변수	필수	설명
GEMINI_API_KEY	예	Google Gemini API 키

커스터마이징

서버는 도구 매개변수를 통해 다양한 설정 옵션을 지원합니다:

• Temperature: 창의성 제어 (0.0-1.0)
• Max Tokens: 응답 길이 제한
• Model Selection: 특정 Gemini 모델 선택
• File Types: 다중 미디어 형식 지원

사용 예제

텍스트 생성

# 도구: gemini_generate
{
  "prompt": "양자 컴퓨팅을 쉬운 말로 설명해주세요",
  "temperature": 0.7,
  "max_tokens": 1000
}

이미지 분석

# 도구: gemini_multimodal
{
  "prompt": "이 이미지에서 보이는 것을 설명해주세요",
  "image_path": "/path/to/image.jpg"
}

코드 실행

# 도구: gemini_code_execution
{
  "prompt": "피보나치 수열을 10개까지 계산하고 그래프로 그려주세요"
}

API 참조

자세한 API 문서는 API_REFERENCE.md를 참조하세요.

기여하기

전 세계 개발자들의 기여를 환영합니다! 🌍

개발 환경 설정

1. 저장소 포크
2. 기능 브랜치 생성
3. 변경사항 작성
4. 테스트 추가
5. 풀 리퀘스트 제출

코딩 표준

• PEP 8 스타일 가이드라인 준수
• 모든 함수에 타입 힌트 추가
• 공개 API에 대한 독스트링 포함
• 포괄적인 오류 처리 작성

라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

---

🌟 Star History

---

💝 Support

If this project helps you, please consider: 이 프로젝트가 도움이 되신다면 고려해주세요:

• ⭐ Starring this repository | 이 저장소에 별점 주기
• 🐛 Reporting bugs | 버그 신고
• 💡 Suggesting features | 기능 제안
• 🔀 Contributing code | 코드 기여
• ☕ Buy us a coffee | 커피 한 잔 사주기

---

🤝 Community

Join our growing community: 성장하는 커뮤니티에 참여하세요:

• GitHub Discussions: Share ideas and get help
• Issues: Report bugs and request features
• Email: codenmsanta@gmail.com for direct contact

---

Made with ❤️ in South Korea | 대한민국에서 사랑으로 제작 🇰🇷