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: 웹 검색
주요 업데이트
최신 버전 (2024-03)
- PM2를 통한 서버 자동화 구현
- gemini-2.0-flash 모델로 통일
- 자동 재시작 및 오류 복구 기능 추가
- 환경 설정 개선
이전 버전
- 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 키 오류 해결 방법
- 일반적인 설치 문제 해결 가이드