MCP Gemini API Server

Google Gemini API server for Cursor and Claude. Provides various Gemini features such as text generation, image analysis, video analysis, etc.

Key Features

• Text generation (using the gemini-2.0-flash model)

• Image creation and analysis

• YouTube video analytics

• Web search

Related MCP server: Gemini Gen MCP

Get started

Essential Requirements

• Node.js 18.0.0 or later

• npm or yarn

• Google API Key (for accessing Gemini API)

installation

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

# 의존성 설치
npm install

Preferences

1. Set your Google API key in config.ts file:

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

Build and Run

# TypeScript 빌드
npm run build

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

# 개발 모드로 실행
npm run dev

PM2 Server Management

The server is automatically managed via PM2. You can manage the server with the following commands:

# 서버 상태 확인
npm run status

# 서버 로그 확인
npm run logs

# 서버 중지
npm run stop

# 서버 재시작
npm run restart

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

Cursor/Claude integration

MCP Settings

Add the following settings to your ~/.cursor/mcp.json file:

{
  "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 endpoint

• /gem-generate : Generate text

• /gem-generate-image : Image generation/analysis

• /gem-analyze-video : Analyze YouTube videos

• /gem-search : Web search

Major Updates

Latest version (2024-03)

• Implementing server automation via PM2

• Unified to gemini-2.0-flash model

• Added automatic restart and error recovery features

• Improve your settings

Previous version

• Added YouTube video analytics feature

• Improved image creation/analysis capabilities

• Add web search functionality

Troubleshooting

Common Problems

1. If the server does not start

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

2. API Key Error

   • Make sure your API key is set correctly in config.ts file.

   • Check Gemini API Quotas and Permissions

3. Memory usage issues

   • Check memory limit settings in ecosystem.config.js

   • Track memory usage with PM2 monitoring

Contribute

1. Fork the Project

2. Create your Feature Branch ( git checkout -b feature/AmazingFeature )

3. Commit your Changes ( git commit -m 'Add some AmazingFeature' )

4. Push to the Branch ( git push origin feature/AmazingFeature )

5. Open a Pull Request

License

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

contact

Project Manager: techkwon Email: techkwon@example.com Project Link: https://github.com/techkwon/mcp-gemini

Key Dependencies

• @google/generative-ai: ^0.1.3 (Gemini API SDK)

• @fastify/cors: ^8.5.0 (CORS support)

• fastify: ^4.29.0 (web server framework)

• googleapis: ^148.0.0 (Google API support)

• typescript: ^5.0.0

• zod: ^3.24.2 (data validation)

• pino: ^8.21.0 (logging)

Claude Desktop App Integration Guide

Settings file location

The settings files for the Claude desktop app are located in the following path:

• Windows: %APPDATA%/Claude/config.json

• macOS: ~/Library/Application Support/Claude/config.json

Example JSON settings

{
  "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}"
            }
          }
        }
      ]
    }
  ]
}

Variable Description

• {uuid} : Unique request ID that is automatically generated.

• {input} : Text entered into Claude's chat window

How to use

1. Open the settings file of the Claude desktop app.

2. Add the JSON settings above to your existing settings.

3. Restart the Claude desktop app.

4. You can use it in the chat window like this:

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

Response Format

All API responses follow this format:

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

Error response

If an error occurs, respond in the following format:

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

Error Handling

The server returns an appropriate error response in the following situations:

• 400: Bad request format

• 401: Authentication error (API key related)

• 500: Internal server error

Security Considerations

• Be sure to manage your API key as an environment variable.

• In a production environment, add appropriate security settings.

• Be careful not to log sensitive information.

Troubleshooting

Port conflict

If port 8000 is already in use:

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

Server Stability

If the server terminates unexpectedly:

• Consider using PM2 or another process manager.

• Check the logs to determine the cause of the termination.

Development Guide

Logging

• Implemented structured logging using Pino logger

• In the development environment, readable logs are output via pino-pretty.

Type safety

• Ensure runtime type safety using TypeScript and Zod

• Schema validation for API requests/responses is implemented.

CLINE MCP Marketplace Registration Guide

Preliminary Preparation

1. Your GitHub repository must be public

2. The README.md file should contain clear installation and setup instructions.

3. (Optional) You can provide additional installation instructions for your AI agent via llms-install.md file.

Registration Procedure

1. Create a new issue in the CLINE MCP Marketplace repository

2. The issue includes the following information:

   • GitHub repository URL: https://github.com/techkwon/mcp-gemini

   • Logo image: PNG file in size 400×400

   • Additional Reason: Example of the value this MCP server can provide to CLINE users: GXP12

3. Tests whether CLINE can successfully install a server with only README.md

Approval process

1. The CLINE team reviews submitted MCP servers

2. We are conducting security and stability verification

3. Once approved, you will be listed on the Marketplace and accessible to all CLINE users.

Optimized installation guide

You can provide additional installation instructions for your AI agent by creating an llms-install.md file:

# 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 키 오류 해결 방법
- 일반적인 설치 문제 해결 가이드