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，请执行以下操作：

npx -y @smithery/cli install @bsmi021/mcp-gemini-server --client claude

手动安装

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 Desktop App 的 claude_desktop_config.json）。将 /path/to/mcp-gemini-server 替换为您系统上的实际路径，并将 YOUR_API_KEY 替换为您的 Google AI Studio 密钥。

   {
     "mcpServers": {
       "gemini-server": { // 或您喜欢的名称
         "command": "node",
         "args": ["/path/to/mcp-gemini-server/dist/server.js"], // 编译后的服务器入口点的路径
         "env": {
           "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY",
           "GOOGLE_GEMINI_MODEL": "gemini-1.5-flash" // 可选：设置默认模型
         },
         "disabled": false,
         "autoApprove": []
       }
       // ... 其他服务器
     }
   }
   

5. 重启 MCP 客户端： 重启您的 MCP 客户端应用程序（例如，带有 Cline 扩展的 VS Code，Claude Desktop App）以加载新的服务器配置。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。
    • 必需参数： 无
  • 可选参数： modelName (字符串), history (数组), tools (数组), generationConfig (对象), safetySettings (数组)
• gemini_sendMessage
  • 描述： 在现有聊天会话中发送消息。
    • 必需参数： sessionId (字符串), message (字符串)
  • 可选参数： generationConfig (对象), safetySettings (数组), tools (数组), toolConfig (对象)
• gemini_sendFunctionResult
  • 描述： 将函数执行的结果发送回聊天会话。
    • 必需参数： sessionId (字符串), functionResponses (数组)
  • 可选参数： generationConfig (对象), safetySettings (数组)

文件处理 (需要 Google AI Studio 密钥)

• gemini_uploadFile
  • 描述： 从本地路径上传文件。 必需参数： filePath (字符串 - 必须是绝对路径)\n 可选参数： displayName (字符串), mimeType (字符串)
• gemini_listFiles
  • 描述： 列出先前上传的文件。
    • 必需参数： 无
  • 可选参数： pageSize (数字), pageToken (字符串 - 注意：目前可能无法可靠地返回 pageToken)。
• gemini_getFile
  • 描述： 检索特定上传文件的元数据。
    • 必需参数： fileName (字符串 - 例如，files/abc123xyz)
• gemini_deleteFile
  • 描述： 删除上传的文件。
    • 必需参数： fileName (字符串 - 例如，files/abc123xyz)

缓存 (需要 Google AI Studio 密钥)

• gemini_createCache
  • 描述： 为兼容的模型（例如，gemini-1.5-flash）创建缓存内容。
    • 必需参数： contents (数组)
  • 可选参数： modelName (字符串), displayName (字符串), systemInstruction (对象), ttl (字符串 - 例如，'3600s')
• gemini_listCaches
  • 描述： 列出现有的缓存内容。
    • 必需参数： 无
  • 可选参数： pageSize (数字), pageToken (字符串 - 注意：目前可能无法可靠地返回 pageToken)。
• gemini_getCache
  • 描述： 检索特定缓存内容的元数据。
    • 必需参数： cacheName (字符串 - 例如，cachedContents/abc123xyz)
• gemini_updateCache
  • 描述： 更新缓存内容的元数据（TTL、displayName）。
    • 必需参数： cacheName (字符串)
  • 可选参数： ttl (字符串), displayName (字符串)
• gemini_deleteCache
  • 描述： 删除缓存内容。
    • 必需参数： 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": "写一首关于橡皮鸭的短诗。"
    }
  </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": "解释编程中递归的概念。",
      "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>

(假设响应包含 sessionId: "some-uuid-123")

发送消息：

<use_mcp_tool>
  <server_name>gemini-server</server_name>
  <tool_name>gemini_sendMessage</tool_name>
  <arguments>
    {
      "sessionId": "some-uuid-123",
      "message": "你好！你能告诉我关于 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", // 重要提示：如果需要，请使用带有转义反斜杠的绝对路径
      "displayName": "我的文档"
    }
  </arguments>
</use_mcp_tool>

错误处理

服务器旨在工具执行失败时使用 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 模式 (src/tools/*Params.ts): 广泛用于定义工具参数，提供验证，并生成对 LLM 交互至关重要的详细描述。
• 配置 (src/config): 通过 ConfigurationManager 进行集中管理。
• 类型 (src/types): 清晰的 TypeScript 定义。

已知问题

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