Servidor MCP Gemini

Descripción general

Este proyecto proporciona un servidor MCP (Protocolo de Contexto de Modelo) dedicado que encapsula el SDK @google/genai . Expone las capacidades del modelo Gemini de Google como herramientas MCP estándar, lo que permite que otros LLM (como Cline) o sistemas compatibles con MCP aprovechen las funciones de Gemini como herramienta principal de backend.

Este servidor tiene como objetivo simplificar la integración con los modelos Gemini al proporcionar una interfaz consistente basada en herramientas administrada a través del estándar MCP.

Características

• Generación de núcleo: generación de texto estándar ( gemini_generateContent ) y de transmisión ( gemini_generateContentStream ).
• Llamada de función: permite que los modelos Gemini soliciten la ejecución de funciones definidas por el cliente ( gemini_functionCall ).
• Chat con estado: administra el contexto conversacional en múltiples turnos ( gemini_startChat , gemini_sendMessage , gemini_sendFunctionResult ).
• Manejo de archivos: cargue, enumere, recupere y elimine archivos mediante la API de Gemini.
• Almacenamiento en caché: cree, enumere, recupere, actualice y elimine contenido en caché para optimizar las indicaciones.

Prerrequisitos

• Node.js (v18 o posterior)
• Una clave API de Google AI Studio ( https://aistudio.google.com/app/apikey ).
  • Importante: Las API de gestión de archivos y almacenamiento en caché solo son compatibles con las claves de API de Google AI Studio y no se admiten al usar credenciales de Vertex AI. Este servidor no admite actualmente la autenticación de Vertex AI.

Instalación y configuración

Instalación mediante herrería

Para instalar Gemini Server para Claude Desktop automáticamente a través de Smithery :

Instalación manual

1. Clonar/Colocar proyecto: asegúrese de que el directorio del proyecto mcp-gemini-server sea accesible en su sistema.
2. Instalar dependencias: navegue al directorio del proyecto en su terminal y ejecute:
   npm install
3. Proyecto de compilación: Compilar el código fuente de TypeScript:
   npm run build
   Este comando usa el compilador TypeScript ( tsc ) y envía los archivos JavaScript al directorio ./dist (como se especifica en outDir en tsconfig.json ). El punto de entrada principal del servidor será dist/server.js .
4. Configurar el cliente MCP: Agregue la configuración del servidor al archivo de configuración de su cliente MCP (p. ej., cline_mcp_settings.json para Cline/VSCode o claude_desktop_config.json para la aplicación de escritorio Claude). Reemplace /path/to/mcp-gemini-server con la ruta real de su sistema y YOUR_API_KEY con su clave de 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 } }
5. Reiniciar el cliente MCP: Reinicie su aplicación cliente MCP (p. ej., VS Code con la extensión Cline, Claude Desktop App) para cargar la nueva configuración del servidor. El cliente MCP gestionará el inicio y la detención del proceso del servidor.

Configuración

El servidor utiliza variables de entorno para la configuración, pasadas a través del objeto env en la configuración de MCP:

• GOOGLE_GEMINI_API_KEY ( Obligatorio ): Su clave API obtenida de Google AI Studio.
• GOOGLE_GEMINI_MODEL ( Opcional ): Especifica un nombre de modelo predeterminado de Gemini (p. ej., gemini-1.5-flash , gemini-1.0-pro ). Si se configura, las herramientas que requieren un nombre de modelo (como gemini_generateContent , gemini_startChat , etc.) usarán este valor predeterminado cuando se omita el parámetro modelName en la llamada a la herramienta. Esto simplifica las llamadas de cliente cuando se usa principalmente un modelo. Si esta variable de entorno no se configura, el parámetro modelName se vuelve obligatorio para esas herramientas. Consulte la documentación de Google AI para conocer los nombres de modelo disponibles.

Herramientas disponibles

Este servidor proporciona las siguientes herramientas MCP. Los esquemas de parámetros se definen mediante Zod para su validación y descripción.

Nota sobre parámetros opcionales: Muchas herramientas aceptan parámetros opcionales complejos (p. ej., generationConfig , safetySettings , toolConfig , history , functionDeclarations , contents ). Estos parámetros suelen ser objetos o matrices cuya estructura refleja los tipos definidos en el SDK @google/genai subyacente. Para conocer la estructura exacta y los campos disponibles dentro de estos parámetros complejos, consulte: 1. El archivo src/tools/*Params.ts correspondiente en este proyecto. 2. La documentación oficial del SDK de Google AI JS .

Generación de núcleo

• gemini_generateContent
  • Descripción: Genera contenido de texto que no se transmite a partir de un mensaje.
  • Parámetros obligatorios: prompt (cadena)
  • Parámetros opcionales: modelName (cadena), generationConfig (objeto), safetySettings (matriz)
• gemini_generateContentStream
  • Descripción: Genera contenido de texto mediante streaming. (Nota: La implementación actual utiliza una solución alternativa y recopila todos los fragmentos antes de devolver el texto completo).
  • Parámetros obligatorios: prompt (cadena)
  • Parámetros opcionales: modelName (cadena), generationConfig (objeto), safetySettings (matriz)

Llamada de función

• gemini_functionCall
  • Descripción: Envía un mensaje y declaraciones de funciones al modelo, devolviendo una respuesta de texto o un objeto de llamada de función solicitado (como una cadena JSON).
  • Parámetros obligatorios: prompt (cadena), functionDeclarations (matriz)
  • Parámetros opcionales: modelName (cadena), generationConfig (objeto), safetySettings (matriz), toolConfig (objeto)

Chat con estado

• gemini_startChat
  • Descripción: Inicia una nueva sesión de chat con estado y devuelve un sessionId único.\n * Parámetros obligatorios: Ninguno
  • Parámetros opcionales: modelName (cadena), history (matriz), tools (matriz), generationConfig (objeto), safetySettings (matriz)
• gemini_sendMessage
  • Descripción: Envía un mensaje dentro de una sesión de chat existente.\n * Parámetros obligatorios: sessionId (cadena), message (cadena)
  • Parámetros opcionales: generationConfig (objeto), safetySettings (matriz), tools (matriz), toolConfig (objeto)
• gemini_sendFunctionResult
  • Descripción: Envía el resultado de la ejecución de una función a una sesión de chat.\n * Parámetros obligatorios: sessionId (cadena), functionResponses (matriz)
  • Parámetros opcionales: generationConfig (objeto), safetySettings (matriz)

Manejo de archivos (se requiere clave de Google AI Studio)

• gemini_uploadFile
  • Descripción: Carga un archivo desde una ruta local.\n Parámetros obligatorios: filePath (cadena - debe ser una ruta absoluta )\n Parámetros opcionales: displayName (cadena), mimeType (cadena)
• gemini_listFiles
  • Descripción: Enumera los archivos cargados previamente.\n * Parámetros obligatorios: Ninguno
  • Parámetros opcionales: pageSize (número), pageToken (cadena; nota: es posible que pageToken no se devuelva de forma confiable actualmente).
• gemini_getFile
  • Descripción: Recupera metadatos para un archivo cargado específico.\n * Parámetros requeridos: fileName (cadena - p. ej., files/abc123xyz )
• gemini_deleteFile
  • Descripción: Elimina un archivo cargado.\n * Parámetros obligatorios: fileName (cadena, por ejemplo, files/abc123xyz )

Almacenamiento en caché (se requiere clave de Google AI Studio)

• gemini_createCache
  • Descripción: Crea contenido en caché para modelos compatibles (por ejemplo, gemini-1.5-flash ).\n * Parámetros obligatorios: contents (matriz)
  • Parámetros opcionales: modelName (cadena), displayName (cadena), systemInstruction (objeto), ttl (cadena, p. ej., '3600s')
• gemini_listCaches
  • Descripción: Enumera el contenido almacenado en caché existente.\n * Parámetros obligatorios: Ninguno
  • Parámetros opcionales: pageSize (número), pageToken (cadena; nota: es posible que pageToken no se devuelva de forma confiable actualmente).
• gemini_getCache
  • Descripción: Recupera metadatos para contenido almacenado en caché específico.\n * Parámetros obligatorios: cacheName (cadena, por ejemplo, cachedContents/abc123xyz )
• gemini_updateCache
  • Descripción: Actualiza los metadatos (TTL, displayName) para el contenido almacenado en caché.\n * Parámetros obligatorios: cacheName (cadena)
  • Parámetros opcionales: ttl (cadena), displayName (cadena)
• gemini_deleteCache
  • Descripción: Elimina el contenido almacenado en caché.\n * Parámetros obligatorios: cacheName (cadena, por ejemplo, cachedContents/abc123xyz )

Ejemplos de uso

A continuación se muestran ejemplos de cómo un cliente MCP (como Cline) podría llamar a estas herramientas utilizando el formato use_mcp_tool :

Ejemplo 1: Generación de contenido simple (utilizando el modelo predeterminado)

Ejemplo 2: Generación de contenido (especificando modelo y configuración)

Ejemplo 3: Iniciar y continuar un chat

Iniciar chat:

(Suponga que la respuesta contiene sessionId: "some-uuid-123" )

Enviar mensaje:

Ejemplo 4: Cargar un archivo

Manejo de errores

El servidor intenta devolver errores estructurados utilizando el tipo McpError estándar de MCP cuando falla la ejecución de la herramienta. Este objeto suele contener:

• code : un valor de enumeración ErrorCode que indica el tipo de error (por ejemplo, InvalidParams , InternalError , PermissionDenied , NotFound ).
• message : Una descripción legible del error.
• details : (opcional) Un objeto que potencialmente contiene información más específica del error subyacente del SDK de Gemini (como motivos de bloqueo de seguridad o mensajes de error de API) para la resolución de problemas.

Escenarios de error comunes:

• Clave API no válida: a menudo genera un InternalError con detalles que indican una falla de autenticación.
• Parámetros no válidos: da como resultado InvalidParams (por ejemplo, campo obligatorio faltante, tipo de datos incorrecto).
• Bloqueos de seguridad: pueden generar un InternalError con detalles que indican SAFETY como el motivo del bloqueo o el motivo de finalización.
• Archivo/caché no encontrado: puede generar NotFound o InternalError según cómo el SDK muestre el error.
• Límites de velocidad: puede resultar en ResourceExhausted o InternalError .

Consulte los campos message y details del McpError devuelto para obtener pistas específicas a la hora de solucionar problemas.

Desarrollo

Este servidor sigue la estructura estándar de servidor MCP descrita en las .clinerules del proyecto y la documentación interna. Los patrones clave incluyen:

• Capa de servicio ( src/services ): encapsula las interacciones con el SDK @google/genai , manteniéndolo desacoplado de las particularidades de MCP.
• Capa de herramientas ( src/tools ): adapta la funcionalidad de la capa de servicio a las herramientas MCP, manejando el mapeo de parámetros y la traducción de errores.
• Esquemas Zod ( src/tools/*Params.ts ): se utilizan ampliamente para definir parámetros de herramientas, proporcionar validación y generar descripciones detalladas cruciales para la interacción LLM.
• Configuración ( src/config ): Gestión centralizada mediante ConfigurationManager .
• Tipos ( src/types ): borra las definiciones de TypeScript.

Problemas conocidos

• gemini_generateContentStream utiliza una solución alternativa: recopila todos los fragmentos antes de devolver el texto completo. La transmisión real al cliente MCP aún no está implementada.
• Es posible que gemini_listFiles y gemini_listCaches no devuelvan nextPageToken de manera confiable debido a limitaciones en la iteración del objeto Pager del SDK.
• gemini_uploadFile requiere rutas de archivos absolutas cuando se ejecuta desde el entorno del servidor.
• Las API de almacenamiento en caché y manejo de archivos no son compatibles con Vertex AI , solo las claves API de Google AI Studio.