Keeping you up to date on AI and Model Context Protocol (MCP)

MCP Gemini API 서버

Cursor와 Claude를 위한 Google Gemini API 서버입니다. 텍스트 생성, 이미지 분석, 비디오 분석 등 Gemini의 다양한 기능을 제공합니다.

주요 기능

텍스트 생성 (gemini-2.0-flash 모델 사용)
이미지 생성 및 분석
YouTube 비디오 분석
웹 검색

시작하기

필수 요구사항

Node.js 18.0.0 이상
npm 또는 yarn
Google API 키 (Gemini API 접근용)

설치

## 저장소 클론
git clone https://github.com/techkwon/mcp-gemini.git
cd mcp-gemini

## 의존성 설치
npm install

환경 설정

config.ts 파일에 Google API 키 설정:

export default {
  googleApiKey: "your_api_key_here",
  // 기타 설정...
};

빌드 및 실행

## TypeScript 빌드
npm run build

## 서버 시작 (PM2 사용)
npm start

## 개발 모드로 실행
npm run dev

PM2 서버 관리

서버는 PM2를 통해 자동으로 관리됩니다. 다음 명령어로 서버를 관리할 수 있습니다:

## 서버 상태 확인
npm run status

## 서버 로그 확인
npm run logs

## 서버 중지
npm run stop

## 서버 재시작
npm run restart

## 시스템 재시작 시 자동 실행 설정
pm2 startup
pm2 save

Cursor/Claude 연동

MCP 설정

~/.cursor/mcp.json 파일에 다음 설정을 추가하세요:

{
  "github.com/techkwon/mcp-gemini": {
    "command": "npm",
    "args": ["start"],
    "cwd": "<프로젝트_경로>",
    "env": {
      "NODE_ENV": "production"
    },
    "disabled": false,
    "autoStart": true,
    "autoApprove": [
      "gem-generate",
      "gem-generate-image",
      "gem-analyze-video",
      "gem-search"
    ]
  }
}

API 엔드포인트

/gem-generate: 텍스트 생성
/gem-generate-image: 이미지 생성/분석
/gem-analyze-video: YouTube 비디오 분석
/gem-search: 웹 검색

주요 업데이트

이전 버전

YouTube 비디오 분석 기능 추가
이미지 생성/분석 기능 개선
웹 검색 기능 추가

문제 해결

일반적인 문제

서버가 시작되지 않는 경우

# PM2 로그 확인
npm run logs

# PM2 프로세스 상태 확인
npm run status

API 키 오류
- config.ts 파일에서 API 키가 올바르게 설정되었는지 확인
- Gemini API 할당량 및 권한 확인
메모리 사용량 문제
- ecosystem.config.js에서 메모리 제한 설정 확인
- PM2 모니터링으로 메모리 사용량 추적

기여하기

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

라이선스

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.

연락처

프로젝트 관리자: techkwon 이메일: techkwon@example.com 프로젝트 링크: https://github.com/techkwon/mcp-gemini

주요 의존성

@google/generative-ai: ^0.1.3 (Gemini API SDK)
@fastify/cors: ^8.5.0 (CORS 지원)
fastify: ^4.29.0 (웹 서버 프레임워크)
googleapis: ^148.0.0 (Google API 지원)
typescript: ^5.0.0
zod: ^3.24.2 (데이터 검증)
pino: ^8.21.0 (로깅)

Claude 데스크톱 앱 통합 가이드

설정 파일 위치

Claude 데스크톱 앱의 설정 파일은 다음 경로에 위치합니다:

Windows: %APPDATA%/Claude/config.json
macOS: ~/Library/Application Support/Claude/config.json

JSON 설정 예시

{
  "apis": [
    {
      "name": "MCP Gemini",
      "url": "http://localhost:8000",
      "methods": [
        {
          "name": "텍스트 생성",
          "method": "gem-generate",
          "template": {
            "jsonrpc": "2.0",
            "id": "{uuid}",
            "method": "gem-generate",
            "params": {
              "prompt": "{input}"
            }
          }
        },
        {
          "name": "이미지 생성",
          "method": "gem-generate-image",
          "template": {
            "jsonrpc": "2.0",
            "id": "{uuid}",
            "method": "gem-generate-image",
            "params": {
              "prompt": "{input}"
            }
          }
        },
        {
          "name": "비디오 분석",
          "method": "gem-analyze-video",
          "template": {
            "jsonrpc": "2.0",
            "id": "{uuid}",
            "method": "gem-analyze-video",
            "params": {
              "videoUrl": "{input}",
              "query": "이 영상의 주요 내용을 요약해주세요"
            }
          }
        },
        {
          "name": "웹 검색",
          "method": "gem-search",
          "template": {
            "jsonrpc": "2.0",
            "id": "{uuid}",
            "method": "gem-search",
            "params": {
              "query": "{input}"
            }
          }
        }
      ]
    }
  ]
}

변수 설명

{uuid}: 자동으로 생성되는 고유 요청 ID
{input}: Claude 채팅창에 입력한 텍스트

사용 방법

Claude 데스크톱 앱의 설정 파일을 엽니다.
위의 JSON 설정을 기존 설정에 추가합니다.
Claude 데스크톱 앱을 재시작합니다.
채팅창에서 다음과 같이 사용할 수 있습니다:

@MCP Gemini.텍스트 생성 한국의 전통 음식에 대해 설명해주세요
@MCP Gemini.이미지 생성 한옥마을의 아름다운 풍경
@MCP Gemini.비디오 분석 https://youtube.com/watch?v=VIDEO_ID
@MCP Gemini.웹 검색 최신 인공지능 기술 동향

응답 형식

모든 API 응답은 다음 형식을 따릅니다:

{
  "jsonrpc": "2.0",
  "id": "요청에서 보낸 ID",
  "result": {
    "content": "응답 내용"
  }
}

오류 응답

오류가 발생한 경우 다음 형식으로 응답합니다:

{
  "jsonrpc": "2.0",
  "id": "요청에서 보낸 ID",
  "error": {
    "code": 오류코드,
    "message": "오류 메시지",
    "data": {
      "details": "상세 오류 정보"
    }
  }
}

오류 처리

서버는 다음과 같은 상황에서 적절한 오류 응답을 반환합니다:

400: 잘못된 요청 형식
401: 인증 오류 (API 키 관련)
500: 서버 내부 오류

보안 고려사항

API 키는 반드시 환경 변수로 관리하세요
프로덕션 환경에서는 적절한 보안 설정을 추가하세요
민감한 정보는 로그에 기록하지 않도록 주의하세요

문제 해결

포트 충돌

이미 8000번 포트가 사용 중인 경우:

## 기존 Node.js 프로세스 종료
pkill -f "node"

서버 안정성

서버가 예기치 않게 종료되는 경우:

PM2나 다른 프로세스 관리자 사용을 고려하세요
로그를 확인하여 종료 원인을 파악하세요

개발 가이드

로깅

Pino 로거를 사용하여 구조화된 로깅을 구현했습니다
개발 환경에서는 pino-pretty를 통해 가독성 있는 로그가 출력됩니다

타입 안정성

TypeScript와 Zod를 사용하여 런타임 타입 안정성을 보장합니다
API 요청/응답에 대한 스키마 검증이 구현되어 있습니다

CLINE MCP 마켓플레이스 등록 가이드

사전 준비사항

GitHub 저장소가 공개되어 있어야 합니다
README.md 파일에 명확한 설치 및 설정 방법이 포함되어 있어야 합니다
(선택사항) llms-install.md 파일을 통해 AI 에이전트를 위한 추가 설치 가이드를 제공할 수 있습니다

등록 절차

CLINE MCP 마켓플레이스 저장소에 새로운 이슈를 생성합니다

이슈에 다음 정보를 포함합니다:

GitHub 저장소 URL: https://github.com/techkwon/mcp-gemini
로고 이미지: 400×400 크기의 PNG 파일
추가 이유: 이 MCP 서버가 CLINE 사용자들에게 제공할 수 있는 가치 예시:

## MCP Gemini 서버 등록 요청

### GitHub 저장소
https://github.com/techkwon/mcp-gemini

### 주요 기능
- Gemini API를 활용한 텍스트 생성
- 이미지 생성 및 편집 (gemini-2.0-flash-exp 모델 사용)
- YouTube 비디오 콘텐츠 분석
- 웹 검색 기능

### 사용자 이점
- 최신 Gemini 모델을 MCP 프로토콜을 통해 쉽게 활용
- 다양한 미디어 형식(텍스트, 이미지, 비디오) 처리 가능
- 명확한 JSON-RPC 인터페이스로 쉬운 통합
- 상세한 문서화와 예제 제공

CLINE이 README.md만으로 서버를 성공적으로 설치할 수 있는지 테스트합니다

승인 절차

CLINE 팀이 제출된 MCP 서버를 검토합니다
보안 및 안정성 검증을 진행합니다
승인되면 마켓플레이스에 등록되어 모든 CLINE 사용자가 접근할 수 있게 됩니다

설치 가이드 최적화

llms-install.md 파일을 생성하여 AI 에이전트를 위한 추가 설치 가이드를 제공할 수 있습니다:

## MCP Gemini 서버 설치 가이드 (AI 에이전트용)

### 환경 요구사항
- Node.js 18.0.0 이상
- npm 또는 yarn
- Google AI Studio API 키

### 설치 단계
1. 저장소 클론
2. 의존성 설치: `npm install`
3. 환경 변수 설정: GOOGLE_API_KEY 추가
4. 빌드: `npm run build`
5. 서버 실행: `npm run start`

### 설정 검증
- 8000번 포트 사용 가능 여부 확인
- API 키 유효성 검증
- CORS 설정 확인

### 문제 해결
- 포트 충돌 시 해결 방법
- API 키 오류 해결 방법
- 일반적인 설치 문제 해결 가이드

MCP Gemini API 서버

주요 기능

시작하기

필수 요구사항

설치

환경 설정

빌드 및 실행

PM2 서버 관리

Cursor/Claude 연동

MCP 설정

API 엔드포인트

주요 업데이트

최신 버전 (2024-03)

이전 버전

문제 해결

일반적인 문제

기여하기

라이선스

연락처

주요 의존성

Claude 데스크톱 앱 통합 가이드

설정 파일 위치

JSON 설정 예시

변수 설명

사용 방법

응답 형식

오류 응답

오류 처리

보안 고려사항

문제 해결

포트 충돌

서버 안정성

개발 가이드

로깅

타입 안정성

CLINE MCP 마켓플레이스 등록 가이드

사전 준비사항

등록 절차

승인 절차

설치 가이드 최적화