MCP Gemini Server

MCP Gemini 服务器

概述

该项目提供了一个专用的 MCP（模型上下文协议）服务器，该服务器封装了@google/genai SDK。它将 Google 的 Gemini 模型功能作为标准 MCP 工具公开，从而允许其他 LLM（例如 Cline）或兼容 MCP 的系统利用 Gemini 的功能作为后端主力。

该服务器旨在通过提供通过 MCP 标准管理的一致的、基于工具的界面来简化与 Gemini 模型的集成。

特征

• **核心生成：**标准（ 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项目目录在您的系统上可访问。
2. **安装依赖项：**导航到终端中的项目目录并运行：
   npm install
3. **构建项目：**编译 TypeScript 源代码：
   npm run build
   此命令使用 TypeScript 编译器 ( tsc )，并将 JavaScript 文件输出到./dist目录（由tsconfig.json中的outDir指定）。主服务器入口点为dist/server.js 。
4. **配置 MCP 客户端：**将服务器配置添加到您的 MCP 客户端设置文件（例如，Cline/VSCode 的cline_mcp_settings.json或 Claude 桌面应用的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 } }
5. **重启 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 ）。设置后，当工具调用中省略了modelName参数时，需要模型名称的工具（例如gemini_generateContent 、 gemini_startChat等）将使用此默认值。当主要使用单个模型时，这可以简化客户端调用。如果未设置此环境变量，则这些工具将需要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**必需参数： filePath （字符串 -必须是绝对路径）\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：简单内容生成（使用默认模型）

示例 2：内容生成（指定模型和配置）

示例 3：开始和继续聊天

开始聊天：

（假设响应包含sessionId: "some-uuid-123" ）

发送消息：

示例 4：上传文件

错误处理

当工具执行失败时，服务器会使用 MCP 标准McpError类型返回结构化错误。此对象通常包含：

• code ：指示错误类型的ErrorCode枚举值（例如， InvalidParams 、 InternalError 、 PermissionDenied 、 NotFound ）。
• message ：错误的人类可读描述。
• details ：（可选）一个对象，可能包含来自底层 Gemini SDK 错误的更多具体信息（如安全阻止原因或 API 错误消息），以便进行故障排除。

常见错误场景：

• **无效的 API 密钥：**通常会导致InternalError ，其详细信息指示身份验证失败。
• **无效参数：**导致InvalidParams （例如，缺少必填字段、错误的数据类型）。
• **安全阻塞：**可能导致InternalError错误，详细信息表明SAFETY是阻塞原因或完成原因。
• **未找到文件/缓存：**可能导致NotFound或InternalError ，具体取决于 SDK 如何显示错误。
• **速率限制：**可能导致ResourceExhausted或InternalError 。

在排查问题时，请查看返回的McpError的message和details字段来寻找具体的线索。

发展

此服务器遵循项目.clinerules和内部文档中概述的标准 MCP 服务器结构。关键模式包括：

• **服务层（ src/services ）：**封装与@google/genai SDK 的交互，使其与 MCP 细节分离。
• **工具层（ src/tools ）：**将服务层功能适配到 MCP 工具，处理参数映射和错误转换。
• **Zod Schemas（ src/tools/*Params.ts ）：**广泛用于定义工具参数、提供验证以及生成对 LLM 交互至关重要的详细描述。
• **配置（ src/config ）：**通过ConfigurationManager进行集中管理。
• **类型（ src/types ）：**清除 TypeScript 定义。

已知问题

• gemini_generateContentStream使用了一种变通方法，在返回全文之前收集所有块。真正的流式传输到 MCP 客户端尚未实现。
• 由于迭代 SDK 的 Pager 对象的限制， gemini_listFiles和gemini_listCaches可能无法可靠地返回nextPageToken 。
• 从服务器环境运行时， gemini_uploadFile需要绝对文件路径。
• Vertex AI 不支持文件处理和缓存 API，仅支持 Google AI Studio API 密钥。