MCP 服务器

MCP Gemini Server

一个 MCP 服务器，它使其他 AI 模型（例如 Claude）能够通过标准化的接口，使用 Google 的 Gemini 模型作为工具来执行特定任务。

README

MCP Gemini 服务器

概述

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

该服务器通过 MCP 标准提供一致的、基于工具的接口，从而简化了与 Gemini 模型的集成。

它能实现什么

简单来说，这个服务器可以让你：

让一个 AI（如 Claude）使用另一个 AI（Gemini）来完成特定任务
通过标准化的接口访问 Gemini 的能力
混合和匹配 AI 能力，而无需管理多个复杂的 API
构建更强大的应用程序，利用不同 AI 模型的最佳功能

可以把它想象成创建了一个通用翻译器，让不同的 AI 系统可以无缝地协同工作。

快速开始

# 克隆仓库
git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

# 创建你的 .env 文件
cp .env.example .env
# 使用来自 https://aistudio.google.com/app/apikey 的 API 密钥编辑 .env

# 安装、构建和运行
npm install
npm run build
npm start

# 健康检查（在另一个终端中）
curl http://localhost:3000/health

使用 Docker：

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server
cp .env.example .env  # 使用你的 API 密钥编辑
docker-compose up -d

或者使用 Docker：

# 克隆和设置
git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server
cp .env.example .env
# 使用你的 API 密钥编辑 .env

# 使用 Docker Compose 运行
docker-compose up -d

# 健康检查
curl http://localhost:3000/health

主要特性

核心生成： 标准 (gemini_generateContent) 和流式 (gemini_generateContentStream) 文本生成。
函数调用： 使 Gemini 模型能够请求执行客户端定义的函数 (gemini_functionCall)。
有状态聊天： 跨多个回合管理对话上下文 (gemini_startChat, gemini_sendMessage, gemini_sendFunctionResult)。
文件处理： 使用 Gemini API 上传、列出、检索和删除文件。
缓存： 创建、列出、检索、更新和删除缓存内容以优化提示。
回退机制： 智能模型回退系统，具有以下功能：
- 当达到配额限制时自动切换到备用模型
- 支持可配置的回退模型链
- 优雅地处理各种超出配额的情况
- 在确保服务连续性的同时保持质量
令牌管理：
- 每个请求可配置的令牌限制
- 自动计算输入令牌
- 防止超出令牌限制
- 优化不同模型版本的上下文窗口

模型回退系统

该服务器实现了一个复杂的回退机制：

主要模型使用：

{
  defaultModel: 'gemini-pro',
  fallbackModels: ['gemini-1.5-flash', 'gemini-1.0-pro']
}

回退触发器：
- 超出配额错误
- 速率限制错误
- 资源耗尽
- 模型特定的不可用
回退过程：
- 首先尝试主要模型
- 在配额/速率限制时，尝试链中的下一个模型
- 保留原始请求参数
- 从第一个可用的模型返回成功
- 仅当所有模型都失败时才抛出错误
错误检测：
- 智能解析错误消息
- 区分配额和其他错误
- 通过回退链维护错误上下文
- 提供详细的错误报告

令牌管理

该服务器智能地处理令牌：

输入令牌计数：
- 在 API 调用之前自动计数
- 尊重模型特定的限制
- 处理多模态内容
- 通过回退保留令牌计数

上下文窗口管理：

{
  maxInputTokens: 30720,  // 模型特定的
  maxOutputTokens: 2048,  // 可配置的
  reserveTokens: 50       // 安全缓冲区
}

令牌优化：
- 动态上下文窗口调整
- 在聊天历史记录中高效使用令牌
- 必要时自动截断
- 保持语义连贯性

前提条件

Node.js (v18 或更高版本)
来自 Google AI Studio 的 API 密钥 (https://aistudio.google.com/app/apikey)。
- 重要提示： 文件处理和缓存 API 仅与 Google AI Studio API 密钥兼容，并且在使用 Vertex AI 凭据时不受支持。此服务器目前不支持 Vertex AI 身份验证。

安装和设置

选项 1：直接开发设置（推荐用于主动开发）

克隆/放置项目：

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

安装依赖项：

npm install

配置环境： 在项目根目录中创建一个 .env 文件：

# 来自 https://aistudio.google.com/app/apikey 的 Google Gemini API 密钥
GOOGLE_GEMINI_API_KEY=your_api_key
GOOGLE_GEMINI_MODEL=gemini-pro  # 可选：设置默认模型

构建项目：

npm run build

启动服务器：

npm start

选项 2：Docker 设置（推荐用于开发/测试）

克隆和配置：

git clone https://github.com/Novakiki/mcp-gemini-server.git
cd mcp-gemini-server

创建环境文件： 创建一个包含你的 API 密钥的 .env 文件：

GOOGLE_GEMINI_API_KEY=your_api_key
GOOGLE_GEMINI_MODEL=gemini-pro

使用 Docker Compose 运行：

docker-compose up -d

服务器将在端口 3000 上可用，并具有自动健康监控和重启功能。

选项 3：MCP 客户端集成

为了与 Cline/VSCode 或 Claude Desktop App 等 MCP 客户端集成：

克隆/放置项目： 确保 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": { // 或者你喜欢的名称
      "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 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 (字符串 - 必须是绝对路径)
- 可选参数： 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：错误类型（例如，InvalidParams、InternalError、NotFound）
message：人类可读的描述
details：（可选）用于故障排除的附加信息

常见错误场景：

错误类型	原因	解决方案
`InternalError`	无效的 API 密钥、安全阻止	检查密钥有效性和内容安全
`InvalidParams`	缺少/错误的参数	验证必需字段和数据类型
`NotFound`	未找到文件/缓存	确认资源存在且可访问
`ResourceExhausted`	超出速率限制	使用回退模型或实施退避

检查 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 定义。

开发工作流程

本地开发：
- 使用 npm run dev 进行热重载
- 运行 npm test 以验证你的更改
- 使用 npm run lint 以保持代码质量
代码质量：
- 在提交之前运行测试：npm test
- 确保 linting 通过：npm run lint
- 遵循 TypeScript 最佳实践
版本控制：
- 从 main 创建特性分支
- 使用有意义的提交消息
- 保持提交的重点和逻辑性
测试更改：
- 使用不同的 Gemini 模型进行测试
- 验证错误处理
- 检查 API 响应

部署选项

直接 Node.js 部署：

npm ci --production
npm run build
npm start

Docker 部署：

docker build -t mcp-gemini-server .
docker run -d \
  -e GOOGLE_GEMINI_API_KEY=your_api_key \
  -e GOOGLE_GEMINI_MODEL=gemini-pro \
  -p 3000:3000 \
  mcp-gemini-server

Docker Compose（推荐）：

docker-compose up -d

生产环境的环境变量：
- GOOGLE_GEMINI_API_KEY：必需
- GOOGLE_GEMINI_MODEL：可选，默认为 gemini-pro
- PORT：可选，默认为 3000
- NODE_ENV：设置为 'production'

健康监控和故障排除

健康端点：/health 提供服务器状态、API 配置和模型可用性。

常见问题：

端口冲突：在 docker-compose.yml 中或通过 PORT 环境变量更改端口
API 密钥问题：在 Google AI Studio 中验证
模型可用性：检查 Google AI 状态页面

调试：

Docker 日志：docker logs mcp-gemini-server
启用详细日志记录：DEBUG=mcp:* 环境变量

已知问题和限制

API 和模型限制

文件处理和缓存 API：这些功能仅在使用 Google AI Studio API 密钥时才受支持，并且在使用 Vertex AI 凭据时不可用。这是 Google Gemini API 本身的限制，而不是我们的实现。
模型可用性：某些模型可能暂时不可用或具有不同的功能。虽然我们的回退系统有助于缓解这种情况，但某些前沿模型可能会遇到：
- 间歇性可用性
- 不同版本之间的功能差异
- 不同的令牌限制
- 区域特定的访问限制
内容安全过滤器：Google 的安全过滤器可能会阻止某些内容生成，这些内容：
- 包含有害内容
- 讨论敏感话题
- 包含某些禁止的类别这些过滤器由 Google 管理，无法完全绕过。

实现限制

流式传输实现：gemini_generateContentStream 工具使用一种解决方法，该方法在返回完整文本之前收集所有块。尚未实现直接流式传输到 MCP 客户端。这意味着：
- 没有增量文本传递
- 感知响应时间较慢
- 大型响应的内存使用率更高
- 无法取消正在进行的生成
分页问题：由于迭代 SDK 的 Pager 对象的限制，gemini_listFiles 和 gemini_listCaches 工具可能无法可靠地返回 nextPageToken。这会影响：
- 列出大型集合
- 遍历所有页面
- 一致的分页体验
文件路径要求：从服务器环境运行时，gemini_uploadFile 工具需要绝对文件路径。这意味着：
- 不支持相对路径
- 服务器进程必须可以访问该路径
- Docker 部署需要卷映射
- 路径格式取决于操作系统
函数调用限制：函数调用功能因模型而异，并且可能具有：
- 跨模型的不一致支持
- 不同的参数处理要求
- 复杂场景中的可靠性各不相同
- 模型特定的函数定义要求

技术解决方法

对于流式传输：如果你需要真正的流式传输：
- 实现自定义服务器扩展
- 使用 WebSockets 进行实时更新
- 考虑服务器发送事件

对于文件路径：使用 Docker 时：

docker run -v /local/path:/container/path -e FILE_PATH=/container/path/file.txt ...

对于分页：实现客户端集合：

// 在客户端代码中收集所有文件
const allFiles = [];
let pageToken = undefined;
do {
  const response = await listFiles({ pageToken, pageSize: 100 });
  allFiles.push(...response.files);
  pageToken = response.nextPageToken;
} while (pageToken);

对于模型限制：设计时要考虑优雅降级：
- 在使用前检查模型功能
- 为不支持的功能提供回退 UX
- 跨多个模型进行测试
- 优雅地处理功能不可用

我们正在积极努力在未来的版本中解决这些限制。