MCP 제미니 서버

대장간 배지

개요

이 프로젝트는 @google/genai SDK를 래핑하는 전용 MCP(모델 컨텍스트 프로토콜) 서버를 제공합니다. Google의 Gemini 모델 기능을 표준 MCP 도구로 제공하여 Cline과 같은 다른 LLM이나 MCP 호환 시스템이 Gemini의 기능을 백엔드 도구로 활용할 수 있도록 합니다.

이 서버는 MCP 표준을 통해 관리되는 일관된 도구 기반 인터페이스를 제공하여 Gemini 모델과의 통합을 단순화하는 것을 목표로 합니다.

Related MCP server: MCP Gemini API Server

특징

핵심 생성: 표준( gemini_generateContent ) 및 스트리밍( gemini_generateContentStream ) 텍스트 생성.
함수 호출: Gemini 모델이 클라이언트 정의 함수( gemini_functionCall )의 실행을 요청할 수 있도록 합니다.
상태 저장 채팅: 여러 턴에 걸쳐 대화 맥락을 관리합니다( gemini_startChat , gemini_sendMessage , gemini_sendFunctionResult ).
파일 처리: Gemini API를 사용하여 파일을 업로드, 나열, 검색 및 삭제합니다.
캐싱: 프롬프트를 최적화하기 위해 캐시된 콘텐츠를 생성, 나열, 검색, 업데이트 및 삭제합니다.

필수 조건

Node.js(v18 이상)
Google AI Studio 의 API 키( https://aistudio.google.com/app/apikey ).
- 중요: 파일 처리 및 캐싱 API는 Google AI Studio API 키와만 호환 되며 Vertex AI 사용자 인증 정보를 사용하는 경우에는 지원되지 않습니다 . 이 서버는 현재 Vertex AI 인증을 지원하지 않습니다.

설치 및 설정

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Gemini Server를 자동으로 설치하려면:

지엑스피1

수동 설치

프로젝트 복제/배치: 시스템에서 mcp-gemini-server 프로젝트 디렉토리에 접근할 수 있는지 확인하세요.
종속성 설치: 터미널에서 프로젝트 디렉토리로 이동하여 다음을 실행합니다.
npm install
프로젝트 빌드: TypeScript 소스 코드를 컴파일합니다.
npm run build
이 명령은 TypeScript 컴파일러( tsc )를 사용하여 JavaScript 파일을 ./dist 디렉터리( tsconfig.json 의 outDir 에 지정된 디렉터리)에 출력합니다. 주 서버 진입점은 dist/server.js 입니다.
MCP 클라이언트 구성: MCP 클라이언트 설정 파일(예: Cline/VSCode의 경우 cline_mcp_settings.json , Claude Desktop App의 경우 claude_desktop_config.json )에 서버 구성을 추가합니다. /path/to/mcp-gemini-server 시스템의 실제 경로로, YOUR_API_KEY Google AI Studio 키로 변경합니다.
{ "mcpServers": { "gemini-server": { // Or your preferred name "command": "node", "args": ["/path/to/mcp-gemini-server/dist/server.js"], // Path to the compiled server entry point "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY", "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash" // Optional: Set a default model }, "disabled": false, "autoApprove": [] } // ... other servers } }
MCP 클라이언트 다시 시작: MCP 클라이언트 애플리케이션(예: Cline 확장 프로그램이 포함된 VS Code, Claude 데스크톱 앱)을 다시 시작하여 새 서버 구성을 로드하세요. MCP 클라이언트가 서버 프로세스의 시작 및 중지를 관리합니다.

구성

서버는 구성을 위해 환경 변수를 사용하며, 이는 MCP 설정의 env 객체를 통해 전달됩니다.

GOOGLE_GEMINI_API_KEY ( 필수 ): Google AI Studio에서 얻은 API 키입니다.
GOOGLE_GEMINI_MODEL ( 선택 사항 ): 기본 Gemini 모델 이름(예: gemini-1.5-flash , gemini-1.0-pro )을 지정합니다. 이 값을 설정하면 모델 이름이 필요한 도구(예: gemini_generateContent , gemini_startChat 등)는 도구 호출에서 modelName 매개변수가 생략될 때 이 기본값을 사용합니다. 이렇게 하면 주로 하나의 모델을 사용하는 클라이언트 호출이 간소화됩니다. 이 환경 변수가 설정되지 않으면 해당 도구에서 modelName 매개변수가 필수가 됩니다. 사용 가능한 모델 이름은 Google AI 문서를 참조하세요.

사용 가능한 도구

이 서버는 다음과 같은 MCP 도구를 제공합니다. 매개변수 스키마는 검증 및 설명을 위해 Zod를 사용하여 정의됩니다.

선택적 매개변수에 대한 참고 사항: 많은 도구가 복잡한 선택적 매개변수(예: generationConfig , safetySettings , toolConfig , history , functionDeclarations , contents )를 허용합니다. 이러한 매개변수는 일반적으로 기본 @google/genai SDK에 정의된 유형을 반영하는 구조를 가진 객체 또는 배열입니다. 이러한 복잡한 매개변수의 정확한 구조와 사용 가능한 필드는 다음을 참조하세요. 1. 이 프로젝트의 해당 src/tools/*Params.ts 파일. 2. 공식 Google AI JS SDK 문서 .

코어 세대

gemini_generateContent
- 설명: 프롬프트에서 스트리밍이 아닌 텍스트 콘텐츠를 생성합니다.
- 필수 매개변수: prompt (문자열)
- 선택 매개변수: modelName (문자열), generationConfig (객체), safetySettings (배열)
gemini_generateContentStream
- 설명: 스트리밍을 통해 텍스트 콘텐츠를 생성합니다. (참고: 현재 구현에서는 임시방편으로 전체 텍스트를 반환하기 전에 모든 청크를 수집합니다.)
- 필수 매개변수: prompt (문자열)
- 선택 매개변수: modelName (문자열), generationConfig (객체), safetySettings (배열)

함수 호출

gemini_functionCall
- 설명: 모델에 프롬프트와 함수 선언을 전송하고, 텍스트 응답이나 요청된 함수 호출 객체(JSON 문자열)를 반환합니다.
- 필수 매개변수: prompt (문자열), functionDeclarations (배열)
- 선택 매개변수: modelName (문자열), generationConfig (객체), safetySettings (배열), toolConfig (객체)

상태 저장 채팅

gemini_startChat
- 설명: 새로운 상태 저장 채팅 세션을 시작하고 고유한 sessionId 반환합니다.\n * 필수 매개변수: 없음
- 선택 매개변수: modelName (문자열), history (배열), tools (배열), generationConfig (객체), safetySettings (배열)
gemini_sendMessage
- 설명: 기존 채팅 세션 내에서 메시지를 보냅니다.\n * 필수 매개변수: sessionId (문자열), message (문자열)
- 선택 매개변수: generationConfig (객체), safetySettings (배열), tools (배열), toolConfig (객체)
gemini_sendFunctionResult
- 설명: 함수 실행 결과를 채팅 세션으로 다시 보냅니다.\n * 필수 매개변수: sessionId (문자열), functionResponses (배열)
- 선택 매개변수: generationConfig (객체), safetySettings (배열)

파일 처리(Google AI Studio 키 필요)

gemini_uploadFile
- 설명: 로컬 경로에서 파일을 업로드합니다.\n 필수 매개변수: 선택 매개변수: displayName (문자열), mimeType (문자열)
gemini_listFiles
- 설명: 이전에 업로드한 파일을 나열합니다.\n * 필수 매개변수: 없음
- 선택 매개변수: pageSize (숫자), pageToken (문자열 - 참고: pageToken 현재 안정적으로 반환되지 않을 수 있음).
gemini_getFile
- 설명: 업로드된 특정 파일의 메타데이터를 검색합니다.\n * 필수 매개변수: fileName (문자열 - 예: files/abc123xyz )
gemini_deleteFile
- 설명: 업로드된 파일을 삭제합니다.\n * 필수 매개변수: fileName (문자열 - 예: files/abc123xyz )

캐싱(Google AI Studio 키 필요)

gemini_createCache
- 설명: 호환 모델(예: gemini-1.5-flash )에 대한 캐시된 콘텐츠를 생성합니다.\n * 필수 매개변수: contents (배열)
- 선택 매개변수: modelName (문자열), displayName (문자열), systemInstruction (객체), ttl (문자열 - 예: '3600s')
gemini_listCaches
- 설명: 기존 캐시된 콘텐츠를 나열합니다.\n * 필수 매개변수: 없음
- 선택 매개변수: pageSize (숫자), pageToken (문자열 - 참고: pageToken 현재 안정적으로 반환되지 않을 수 있음).
gemini_getCache
- 설명: 특정 캐시된 콘텐츠에 대한 메타데이터를 검색합니다.\n * 필수 매개변수: cacheName (문자열 - 예: cachedContents/abc123xyz )
gemini_updateCache
- 설명: 캐시된 콘텐츠에 대한 메타데이터(TTL, displayName)를 업데이트합니다.\n * 필수 매개변수: cacheName (문자열)
- 선택 매개변수: ttl (문자열), displayName (문자열)
gemini_deleteCache
- 설명: 캐시된 콘텐츠를 삭제합니다.\n * 필수 매개변수: cacheName (문자열 - 예: cachedContents/abc123xyz )

사용 예

다음은 MCP 클라이언트(Cline 등)가 use_mcp_tool 형식을 사용하여 이러한 도구를 호출하는 방법의 예입니다.

예제 1: 간단한 콘텐츠 생성(기본 모델 사용)

<use_mcp_tool> <server_name>gemini-server</server_name> <tool_name>gemini_generateContent</tool_name> <arguments> { "prompt": "Write a short poem about a rubber duck." } </arguments> </use_mcp_tool>

예제 2: 콘텐츠 생성(모델 및 구성 지정)

<use_mcp_tool> <server_name>gemini-server</server_name> <tool_name>gemini_generateContent</tool_name> <arguments> { "modelName": "gemini-1.0-pro", "prompt": "Explain the concept of recursion in programming.", "generationConfig": { "temperature": 0.7, "maxOutputTokens": 500 } } </arguments> </use_mcp_tool>

예제 3: 채팅 시작 및 계속

채팅 시작:

<use_mcp_tool> <server_name>gemini-server</server_name> <tool_name>gemini_startChat</tool_name> <arguments> {} </arguments> </use_mcp_tool>

(응답에

메시지 보내기:

<use_mcp_tool> <server_name>gemini-server</server_name> <tool_name>gemini_sendMessage</tool_name> <arguments> { "sessionId": "some-uuid-123", "message": "Hello! Can you tell me about the Gemini API?" } </arguments> </use_mcp_tool>

예제 4: 파일 업로드

<use_mcp_tool> <server_name>gemini-server</server_name> <tool_name>gemini_uploadFile</tool_name> <arguments> { "filePath": "C:\\Users\\YourUser\\Documents\\my_document.txt", // IMPORTANT: Use absolute path with escaped backslashes if needed "displayName": "My Document" } </arguments> </use_mcp_tool>

오류 처리

서버는 도구 실행이 실패할 때 MCP 표준 McpError 유형을 사용하여 구조화된 오류를 반환하는 것을 목표로 합니다. 이 객체는 일반적으로 다음을 포함합니다.

code : 오류 유형을 나타내는 ErrorCode 열거형 값(예: InvalidParams , InternalError , PermissionDenied , NotFound ).
message : 오류에 대한 사람이 읽을 수 있는 설명입니다.
details : (선택 사항) 문제 해결을 위해 기본 Gemini SDK 오류(예: 안전 차단 이유 또는 API 오류 메시지)에서 보다 구체적인 정보를 포함할 수 있는 객체입니다.

일반적인 오류 시나리오:

잘못된 API 키: 인증 실패를 나타내는 세부 정보와 함께 InternalError 발생하는 경우가 많습니다.
잘못된 매개변수: InvalidParams 발생합니다(예: 필수 필드 누락, 잘못된 데이터 유형).
안전 차단: 차단 사유가 SAFETY이거나 완료 사유가 SAFETY 인 경우 InternalError 가 발생할 수 있습니다.
파일/캐시를 찾을 수 없음: SDK가 오류를 표시하는 방식에 따라 NotFound 또는 InternalError 가 발생할 수 있습니다.
속도 제한: ResourceExhausted 또는 InternalError 가 발생할 수 있습니다.

문제 해결 시 구체적인 단서를 얻으려면 반환된 McpError 의 message 및 details 필드를 확인하세요.

개발

이 서버는 프로젝트의 .clinerules 및 내부 문서에 명시된 표준 MCP 서버 구조를 따릅니다. 주요 패턴은 다음과 같습니다.

서비스 계층( @google/genai SDK와의 상호작용을 캡슐화하여 MCP 세부 사항과 분리합니다.
도구 계층( 서비스 계층 기능을 MCP 도구에 맞춰 조정하여 매개변수 매핑과 오류 변환을 처리합니다.
Zod 스키마( 도구 매개변수 정의, 검증 제공, LLM 상호 작용에 중요한 자세한 설명 생성에 광범위하게 사용됩니다.
구성( ConfigurationManager 통한 중앙 관리.
유형( 명확한 TypeScript 정의.

알려진 문제

gemini_generateContentStream 전체 텍스트를 반환하기 전에 모든 청크를 수집하는 임시 방편을 사용합니다. MCP 클라이언트로의 실제 스트리밍은 아직 구현되지 않았습니다.
gemini_listFiles 및 gemini_listCaches SDK의 Pager 객체를 반복하는 데 있어 제한이 있어 nextPageToken 안정적으로 반환하지 못할 수 있습니다.
gemini_uploadFile 서버 환경에서 실행할 때 절대 파일 경로가 필요합니다.
Vertex AI에서는 파일 처리 및 캐싱 API가 지원되지 않으며 , Google AI Studio API 키만 지원됩니다.

MCP Gemini Server