MCP Gemini 服务

@bsmi021/mcp-gemini-server

0 Stars 336 次浏览 bsmi021 更新于 2026-08-23

一台专用服务器，它将谷歌的Gemini人工智能模型封装在模型上下文协议（MCP）接口中，使其他大型语言模型和兼容MCP的系统能够通过标准化工具访问Gemini的功能，如内容生成、函数调用、聊天和文件处理。

开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

MCP Gemini 服务器

概述

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

此服务器旨在通过提供一个一致的、基于工具的接口来简化与 Gemini 模型的集成，该接口通过 MCP 标准进行管理。

功能

核心生成： 标准文本生成 (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 服务器：

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

手动安装

请继续提供手动安装的具体步骤，以便我完成翻译。如果还有更多需要翻译的内容，请一并提供。

克隆/放置项目： 确保 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 桌面应用程序的 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": []
    }
    // ... 其他服务器
  }
}

重启 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 密钥）

请注意，原文档中的最后一部分“File Handling (Google AI Studio Key Required)”没有提供具体内容，因此保持原样。如果这部分有更多信息，请提供以便进一步翻译。

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：简单内容生成（使用默认模型）

<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>

假设响应包含 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": "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（例如，缺少必填字段、数据类型错误）。
安全拦截： 可能导致 InternalError，详细信息中会指出拦截原因是 SAFETY。
文件/缓存未找到： 根据 SDK 报错方式的不同，可能导致 NotFound 或 InternalError。
速率限制： 可能导致 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 密钥。

查看源码项目主页