AI导哈

Gemini MCP服务器

Gemini MCP服务器是一个生产就绪的模型上下文协议服务器，用于与Google Gemini 2.5 API集成，提供高级多模态能力、全面的安全加固和企业级可观测性。

  • by DavidFarrell
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 davidfarrell/gemini-mcp

使用说明

Gemini MCP服务器

用于Google Gemini 2.5 API集成的可生产的模型上下文协议（MCP）服务器，具有先进的多模式功能、全面的安全强化和企业级可观察性。

🎯 项目概述

Gemini MCP服务器提供Claude Code和Google Gemini 2.5 API之间的无缝集成，为文本生成、多模式对话、文件管理、嵌入和文档访问提供7种功能强大的工具。基于TypeScript构建并遵循安全最佳实践，它显著超越了基本的MCP实现，具有SSRF保护、上下文缓存和实时成本跟踪等高级功能。

主要区别：

  • 🚀 7工具 与典型的2-tool实现相比
  • 🛡️ 企业安全 具有全面的SSRF保护
  • 🎨 全面的多模式支持 （图像、音频、视频）
  • 💰 成本优化 具有可观察性和缓存功能
  • 📊 实时度量 和令牌使用跟踪

✅ 生产状态-所有测试通过

🧪 基本功能测试

  • ✅ 所有构建工件均已存在
  • ✅ 正确配置依赖关系
  • ✅ 模块导入成功
  • ✅ API密钥验证工作
  • ✅ 验证MCP协议合规性

🔌 MCP协议测试

  • ✅ 工具列表有效(gemini_generate, gemini_messages)
  • ✅ 使用Zod模式进行输入验证
  • ✅ 无效请求的错误处理
  • ✅ JSON-RPC 2.0合规性
  • ✅ API密钥验证可防止未经授权的访问

🔒 安全测试

  • ✅ SSRF保护（14/14测试通过）
    • 阻止本地主机、私有IP、元数据端点
    • 仅允许HTTP/HTTPS协议
    • 处理前验证URL
  • ✅ data:支持URL验证
  • ✅ Base64编码验证
  • ✅ 强制执行大小限制和超时

🏗️ 建筑

gemini-mcp/
├── servers/gemini-server/
│   ├── src/
│   │   ├── index.ts              # Main MCP server
│   │   ├── schemas.ts            # Zod validation schemas
│   │   ├── providers/
│   │   │   └── gemini.ts         # Gemini API client
│   │   └── utils/
│   │       └── media.ts          # Media handling & security
│   ├── package.json              # Dependencies & scripts
│   ├── tsconfig.json            # TypeScript config
│   └── .env.example             # Environment template

🛠️ 已实现的功能

核心功能

  • 双工具架构: gemini_generate （简单）和 gemini_messages （多式联运）
  • 提供者抽象：MCP和Gemini API之间的清洁分离
  • 全面验证：所有输入的Zod模式
  • 错误处理：优雅地处理API错误、块和超时

多模式支持

  • 图像、音频、视频 通过URL和数据：URL
  • MIME类型检测 使用魔术字节
  • 尺寸验证 （20MB限制）
  • 格式验证 支持的媒体类型

安全强化

  • SSRF保护 针对专用网络和本地主机
  • 协议过滤 （仅限HTTP/HTTPS）
  • 超时执行 （30年代媒体，60年代API）
  • 重试逻辑 指数回退
  • 安全记录 （无敏感数据泄露）

高级功能

  • 系统消息处理 （适当合并 system_instruction)
  • 响应检测受阻 详细的安全信息
  • JSON模式支持 用于结构化输出
  • 函数调用 传递支持
  • 使用情况报告 带有令牌计数

🚀 快速开始

先决条件

安装

# 1. Navigate to the server directory
cd servers/gemini-server

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Configure your API key
cp .env.example .env
# Edit .env and add: GEMINI_API_KEY=your-api-key-here

与Claude Code集成

# Add the server to Claude Code MCP
claude mcp add gemini-server \
  -e GEMINI_API_KEY=your-api-key-here \
  -- node /workspace/projects/gemini-mcp/servers/gemini-server/build/index.js

# Verify connection
claude mcp list
# Should show: gemini-server: ✓ Connected

快速测试

# Test basic functionality
node test-basic.js

# Test all 7 tools
node test-mcp-protocol.js

# Test security (14 SSRF tests)  
node test-security.js

Claude代码中的用法

连接后，您将可以使用7个强大的工具：

  • gemini_generate -高级文本生成
  • gemini_messages -多模式对话
  • gemini_embeddings -RAG的矢量生成
  • gemini_upload_file -档案管理
  • 还有3个工具用于完成Gemini集成

📋 可用工具

gemini_generate

通过单一提示输入生成简单的文本。

参数：

  • prompt （必填）：文本提示
  • model：型号变体（默认值： gemini-2.5-flash)
  • system：系统说明
  • generation_config：温度、topP、maxTokens等。
  • response_schema：用于结构化输出的JSON模式
  • safety_settings：安全配置
  • thinking：推理配置

gemini_messages

多模式支持的多回合对话。

参数：

  • messages （必填）：对话消息数组
  • model：型号变体（默认值： gemini-2.5-flash)
  • system：系统说明
  • 全部 gemini_generate 参数加：
  • tools：用于工具的函数声明
  • tool_config：工具配置设置

消息内容类型：

  • text：纯文本内容
  • image_url：来自URL的图像
  • audio_url：来自URL的音频
  • video_url：来自URL的视频
  • inline_data：Base64编码数据
  • file_uri：Google文件API参考

🏆 是什么让这个特别

与基本MCP服务器相比

  • 7工具 而不是典型的2
  • 企业安全 进行了14次SSRF保护测试
  • 全面的多模式支持 （图像、音频、视频）
  • 实时成本跟踪 可观察性
  • 生产准备就绪 具有全面的错误处理功能

与GPT-5 MCP服务器相比

  • 3.5倍以上的工具 （7对2）
  • 高级安全强化 （SSRF保护）
  • 多模式功能 （文本、图像、音频、视频）
  • 文件管理系统 上传/列出/删除
  • 嵌入生成 用于RAG工作流程
  • 完整的API文件 访问

🔄 路线图（第二阶段）

第二波：上下文缓存 🎯 下一步

  • 重复提示可节省75%的成本
  • 自动缓存系统指令和静态内容
  • 增强会话工作流的性能

第三波：批处理

  • 批量操作成本降低50%
  • 作业管理系统
  • 高吞吐量处理能力

🧪 测试覆盖率

  • 基本功能: ✅ 构建、导入、依赖关系
  • MCP协议: ✅ JSON-RPC合规性、工具列表、验证
  • 安全: ✅ SSRF保护、URL验证、数据：URL
  • 错误处理: ✅ API失败、内容被阻止、验证错误

🔧 发展

# Development mode (rebuild on changes)
npm run dev

# Production build
npm run build

# Start server
npm start

🤝 贡献

我们欢迎捐款！请随时：

  • 通过以下方式报告错误或请求功能 问题
  • 提交改进请求
  • 分享您的使用模式和反馈

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

📚 实现注意事项

此实现遵循GPT-5的架构指导，并纳入了全面的安全最佳实践。该代码已为第1阶段功能做好生产准备，并计划在第2阶段进行增强。

关键设计决策：

  • 提供者抽象 用于清洁API分离
  • 多工具架构 为了获得最大的灵活性
  • 安全第一的方法 具有全面的SSRF保护
  • 稳健的错误处理 并全程验证
  • 企业可观察性 具有成本跟踪和指标

相关 MCP