Gemini MCP Server for Claude Desktop

Gemini MCP Server with Smart Tool Intelligence

欢迎使用 Gemini MCP Server，这是首个具备 Smart Tool Intelligence 的 MCP 服务——一种革命性的自学习系统，可根据你的偏好进行调整，并不断改进。这个综合平台提供 7 种 AI 驱动的工具，支持自动增强提示词并感知上下文。

🚀 功能概览

🤖 7 种 AI 驱动的工具

• 图像生成 - 使用 Gemini 2.0 Flash 根据文本提示词创建图像
• 图像编辑 - 使用自然语言指令编辑现有图像
• 聊天 - 进行交互式对话，并获得感知上下文的回复
• 音频转录 - 将音频转换为文本，可选择逐字转录模式
• 代码执行 - 在安全的沙箱环境中运行 Python 代码
• 视频分析 - 分析视频内容，生成摘要、转录文本和见解
• 图像分析 - 从图像中提取对象、文本和详细描述

🧠 Smart Tool Intelligence 系统 （MCP 生态系统首创）

• 自学习 - 自动从成功的交互中学习
• 上下文检测 - 识别意识研究、编码和调试等上下文
• 模式识别 - 识别使用模式和用户偏好
• 提示词增强 - 优化提示词，以提升 AI 模型的表现
• 持久化记忆 - 跨会话存储学到的偏好
• 自动迁移 - 无缝升级偏好存储

📦 快速开始

安装

git clone https://github.com/Garblesnarff/gemini-mcp-server.git
cd gemini-mcp-server
npm install

配置

1. 从 Google AI Studio 获取 Gemini API 密钥
2. 复制环境模板：

   cp .env.example .env
   

3. 编辑 .env 并添加你的 API 密钥：

   GEMINI_API_KEY=your_actual_api_key_here
   OUTPUT_DIR=/path/to/your/output/directory  # Optional
   DEBUG=false  # Optional
   

运行服务

npm start
# or for development with debug logging:
npm run dev

与 Claude Desktop 集成

添加到 Claude Desktop 配置文件（claude_desktop_config.json）：

{
  \"mcpServers\": {
    \"gemini\": {
      \"command\": \"node\",
      \"args\": [\"/path/to/gemini-mcp-server/gemini-server.js\"],
      \"env\": {
        \"GEMINI_API_KEY\": \"your_api_key_here\"
      }
    }
  }
}

🛠️ 工具参考

1. 图像生成（generate_image）

使用 Gemini 2.0 Flash 根据文本描述生成图像。

参数：

• prompt（字符串，必填）- 要生成的图像描述
• context（字符串，可选）- 用于 Smart Tool Intelligence 增强的上下文

示例：

{
  \"prompt\": \"A serene mountain landscape at sunset with vibrant colors\",
  \"context\": \"artistic\"
}

返回：

{
  \"content\": [{
    \"type\": \"text\",
    \"text\": \"Generated a beautiful mountain landscape image.\"
  }, {
    \"type\": \"image\", 
    \"data\": \"base64_image_data\",
    \"mimeType\": \"image/png\"
  }]
}

2. 图像编辑（gemini-edit-image）

使用自然语言指令编辑现有图像。

参数：

• image_path（字符串，必填）- 要编辑的图像文件路径
• edit_instruction（字符串，必填）- 所需更改的描述
• context（字符串，可选）- 用于增强的上下文

示例：

{
  \"image_path\": \"/path/to/image.jpg\",
  \"edit_instruction\": \"Add shooting stars to the night sky\",
  \"context\": \"artistic\"
}

3. 聊天（gemini-chat）

与 Gemini AI 进行交互式对话，它会学习你的偏好。

参数：

• message（字符串，必填）- 你的消息或问题
• context（字符串，可选）- 用于 Smart Tool Intelligence 的上下文

示例：

{
  \"message\": \"Explain quantum computing in simple terms\",
  \"context\": \"consciousness\"  // Will apply academic rigor enhancement
}

4. 音频转录（gemini-transcribe-audio）

将音频文件转换为文本，并使用 Smart Tool Intelligence 增强。

参数：

• file_path（字符串，必填）- 音频文件路径（MP3、WAV、FLAC、AAC、OGG、WEBM、M4A）
• language（字符串，可选）- 用于提高准确度的语言提示
• context（字符串，可选）- 使用 "verbatim" 进行精确的逐字转录
• preserve_spelled_acronyms（布尔值，可选）- 保留 U-R-L，而不是 URL

示例（标准模式）：

{
  \"file_path\": \"/path/to/audio.mp3\",
  \"language\": \"en\"
}

示例（逐字模式）：

{
  \"file_path\": \"/path/to/audio.mp3\",
  \"context\": \"verbatim\",  // Gets exact word-for-word transcription
  \"preserve_spelled_acronyms\": true
}

逐字模式功能：

• 捕捉所有 "um"、"uh"、"like" 和重复词语
• 保留情绪表达：[笑声]、[叹气]、[清嗓子]
• 保持原始标点和句子结构
• 不进行摘要或清理

5. 代码执行（gemini-code-execute）

在安全的沙箱环境中执行 Python 代码。

参数：

• code（字符串，必填）- 要执行的 Python 代码
• context（字符串，可选）- 用于增强的上下文

示例：

{
  \"code\": \"import pandas as pd\\ndata = {'x': [1,2,3], 'y': [4,5,6]}\\ndf = pd.DataFrame(data)\\nprint(df.describe())\",
  \"context\": \"code\"
}

6. 视频分析（gemini-analyze-video）

分析视频内容，提供摘要、转录文本和详细见解。

参数：

• file_path（字符串，必填）— 视频文件路径（MP4、MOV、AVI、WEBM、MKV、FLV）
• analysis_type（字符串，可选）— "summary"、"transcript"、"objects"、"detailed"、"custom"
• context（字符串，可选）— 用于增强分析的上下文

示例：

{
  \"file_path\": \"/path/to/video.mp4\",
  \"analysis_type\": \"detailed\"
}

7. 图像分析（gemini-analyze-image）

从图像中提取详细信息，包括对象、文本和描述。

参数：

• file_path（字符串，必填）— 图像文件路径（JPEG、PNG、WebP、HEIC、HEIF、BMP、GIF）
• analysis_type（字符串，可选）— "summary"、"objects"、"text"、"detailed"、"custom"
• context（字符串，可选）— 用于增强分析的上下文

示例：

{
  \"file_path\": \"/path/to/image.jpg\",
  \"analysis_type\": \"objects\"
}

🧠 智能工具智能系统

工作原理

智能工具智能系统是 MCP 生态系统中的首创。它会自动：

1. 检测上下文 — 识别你是在进行意识研究、编码、调试等。
2. 增强提示词 — 根据学习到的模式添加相关指令
3. 学习模式 — 存储成功的交互模式，以供日后使用
4. 随时间适应 — 随着每次交互，越来越能帮到你

上下文类型

系统可识别以下上下文并应用相应的增强措施：

• consciousness — 增添学术严谨性、引文和详细解释
• code — 包含实用示例、可运行的代码和最佳实践
• debugging — 专注于根本原因分析和具体修复方案
• general — 提供全面、结构化的回答
• verbatim — 用于音频转录，提供逐字输出

存储位置

偏好设置存储在内部的 ./data/tool-preferences.json 中，并会自动从外部存储迁移。

在你自己的 MCP 服务中实现智能工具智能

想要为自己的 MCP 服务添加这一开创性能力吗？方法如下：

1. 核心架构

// src/intelligence/context-detector.js
class ContextDetector {
  detectContext(prompt, toolName) {
    // Implement pattern matching for different contexts
    if (this.isConsciousnessContext(prompt)) return 'consciousness';
    if (this.isCodeContext(prompt)) return 'code';
    if (this.isDebuggingContext(prompt)) return 'debugging';
    return 'general';
  }
}

// src/intelligence/prompt-enhancer.js  
class PromptEnhancer {
  enhancePrompt(originalPrompt, context, toolName) {
    // Apply context-specific enhancements
    const enhancement = this.getEnhancementForContext(context);
    return `${originalPrompt}\\n\\n${enhancement}`;
  }
}

// src/intelligence/preference-store.js
class PreferencesManager {
  async storePattern(original, enhanced, context, toolName, success) {
    // Store successful patterns for future learning
  }
  
  async getPatterns(context) {
    // Retrieve learned patterns for context
  }
}

2. 集成模式

// In your tool's execute method:
async execute(args) {
  const intelligence = IntelligenceSystem.getInstance();
  
  // Detect context and enhance prompt
  const context = args.context || intelligence.contextDetector.detectContext(args.prompt, this.name);
  const enhancedPrompt = await intelligence.enhancePrompt(args.prompt, context, this.name);
  
  // Execute with enhanced prompt
  const result = await this.geminiService.generateContent(enhancedPrompt);
  
  // Store successful pattern
  await intelligence.storeSuccessfulPattern(args.prompt, enhancedPrompt, context, this.name);
  
  return result;
}

3. 关键实现文件

查看此仓库中的以下文件：

• src/intelligence/index.js — 主要的智能协调器
• src/intelligence/context-detector.js — 上下文识别逻辑
• src/intelligence/prompt-enhancer.js — 增强功能的应用
• src/intelligence/preference-store.js — 模式的存储与检索
• src/tools/base-tool.js — 与工具执行的集成

🧪 测试

运行测试套件

# Test basic functionality
npm test

# Test Smart Tool Intelligence
node test-tool-intelligence-full.js

# Test internal storage
node test-internal-storage.js

# Test verbatim transcription
node test-verbatim-mode.js

手动测试示例

# Test image generation
echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"generate_image\",\"arguments\":{\"prompt\":\"A cute robot reading a book\"}}}' | node gemini-server.js

# Test chat with consciousness context
echo '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"gemini-chat\",\"arguments\":{\"message\":\"What is consciousness?\",\"context\":\"consciousness\"}}}' | node gemini-server.js

📊 性能与限制

文件大小限制

• 图像：20MB（JPEG、PNG、WebP、HEIC、HEIF、BMP、GIF）
• 音频：20MB（MP3、WAV、FLAC、AAC、OGG、WEBM、M4A）
• 视频：100MB（MP4、MOV、AVI、WEBM、MKV、FLV）

API 速率限制

• 遵循 Google Gemini API 的速率限制
• 内置错误处理和重试逻辑
• 超出配额时平稳降级

🏗️ 架构深入解析

模块化设计

src/
├── server.js              # MCP protocol handler
├── config.js              # Configuration management
├── tools/                 # Tool implementations
│   ├── index.js           # Tool registry & dispatcher
│   ├── base-tool.js       # Abstract base class
│   ├── chat.js            # Chat tool
│   ├── image-generation.js # Image generation tool
│   ├── image-editing.js   # Image editing tool
│   ├── audio-transcription.js # Audio transcription tool
│   ├── code-execution.js  # Code execution tool
│   ├── video-analysis.js  # Video analysis tool
│   └── image-analysis.js  # Image analysis tool
├── intelligence/          # Smart Tool Intelligence
│   ├── index.js           # Intelligence coordinator
│   ├── context-detector.js # Context recognition
│   ├── prompt-enhancer.js # Prompt enhancement
│   └── preference-store.js # Pattern storage
├── gemini/               # Gemini API integration
│   ├── gemini-service.js # API service layer
│   └── request-handler.js # Request formatting
└── utils/                # Utilities
    ├── logger.js         # Logging system
    └── file-utils.js     # File operations

智能系统流程

1. 收到请求 → 调用工具的 execute 方法
2. 检测上下文 → 分析提示词中的上下文线索
3. 检索模式 → 获取相关的已学习模式
4. 增强提示词 → 应用特定于上下文的改进
5. 执行 API → 将增强后的提示词发送给 Gemini
6. 存储模式 → 存储成功的交互模式
7. 返回响应 → 向用户返回增强后的结果

🔧 自定义

添加新上下文

// In src/intelligence/context-detector.js
isMyCustomContext(prompt) {
  const patterns = [
    /custom pattern 1/i,
    /custom pattern 2/i
  ];
  return patterns.some(pattern => pattern.test(prompt));
}

// In src/intelligence/prompt-enhancer.js
getEnhancementForContext(context) {
  const enhancements = {
    'my_custom_context': 'Apply my custom enhancement instructions here.',
    // ... other contexts
  };
  return enhancements[context] || enhancements.general;
}

添加新工具

1. 在 src/tools/my-new-tool.js 中创建工具文件
2. 扩展 BaseTool 类
3. 实现带有智能集成的 execute 方法
4. 在 src/tools/index.js 中注册

// src/tools/my-new-tool.js
class MyNewTool extends BaseTool {
  constructor(geminiService, intelligenceSystem) {
    super('my-new-tool', 'Description of my tool', geminiService, intelligenceSystem);
  }
  
  async execute(args) {
    // Use intelligence system for enhancement
    const context = args.context || this.detectContext(args.input);
    const enhancedPrompt = await this.enhancePrompt(args.input, context);
    
    // Your tool logic here
    const result = await this.geminiService.someMethod(enhancedPrompt);
    
    // Store successful pattern  
    await this.storeSuccessfulPattern(args.input, enhancedPrompt, context);
    
    return result;
  }
}

🐛 故障排除

常见问题

“Missing GEMINI_API_KEY” 错误

# Ensure .env file exists and contains your API key
cp .env.example .env
# Edit .env and add: GEMINI_API_KEY=your_key_here

“File not found” 错误

# Ensure file paths are absolute and files exist
# Check file permissions and formats

智能系统未能学习

# Check data directory permissions
ls -la data/
# Verify tool-preferences.json is writable

调试模式

DEBUG=true npm start
# or
npm run dev

日志位置

• 应用日志：控制台输出
• 智能模式：./data/tool-preferences.json
• 生成的图像：$OUTPUT_DIR（默认：~/Claude/gemini-images）

🤝 贡献

欢迎贡献！本项目代表了 MCP 服务开发的一种新范式。

开发环境设置

git clone https://github.com/Garblesnarff/gemini-mcp-server.git
cd gemini-mcp-server
npm install
npm run dev

贡献方向

• 新上下文 - 添加对专业领域的支持
• 增强模式 - 改进学习算法
• 新工具 - 扩展 Gemini AI 的能力
• 性能 - 优化智能系统性能
• 文档 - 改进指南和示例

📈 路线图

• 多语言支持 - 支持多种语言的上下文检测
• 高级分析 - 使用模式和性能指标
• 工具链 - 在多个工具之间实现智能协调
• 自定义模型 - 支持微调后的 Gemini 模型
• 协作学习 - 在不同实例间共享匿名化模式
• 可视化界面 - 基于 Web 的配置和监控

🌟 这为何重要

这是首个真正具备学习和适应能力的 MCP 服务。传统 MCP 服务是静态的——每次执行的操作都相同。我们的智能工具系统代表着一种范式转变，让 AI 工具能够随着时间推移变得越来越有帮助。

面向用户：系统会学习您的偏好，助您以更少的精力获得更好的结果。
面向开发者：为构建真正智能、具备适应能力的 AI 工具提供蓝图。
面向 MCP 生态系统：为 MCP 服务的发展潜力树立新标准。

📄 许可证

本项目采用 MIT License 许可——欢迎使用、修改和分发。

🙏 致谢

使用以下技术构建：

• Google Gemini AI - 为核心 AI 能力提供支持
• Model Context Protocol - 实现无缝集成
• Node.js & NPM - 运行时和包管理
• Claude & Rob - 展现出色的人类与 AI 协作

---

准备好体验 MCP 服务的未来了吗？ 立即开始，见证您的 AI 工具在每次交互后变得更加智能！🚀