Gemini MCP

Gemini MCP - 基于 Gemini 的智能图像分析服务

项目概述

Gemini MCP 是一个基于 Google Gemini 2.0 Flash 模型的 MCP（Model Context Protocol）服务器，专门用于图像分析和处理。它可以无缝集成到 Claude Desktop、Cursor 等支持 MCP 协议的 AI 助手中，提供强大的视觉理解能力。

核心特性

🎯 主要功能

多模态分析：支持图片内容理解、场景识别、文字提取等
灵活输入：支持本地文件路径、网络 URL、Base64 编码等多种图片输入方式
流式响应：实时流式输出分析结果，提升用户体验
智能存储：自动保存处理结果和生成的图片

🚀 技术优势

零依赖安装：支持 uvx 直接运行，无需预先安装
跨平台兼容：支持 macOS、Windows、Linux 等主流操作系统
代理支持：内置 SOCKS5 代理支持，适应各种网络环境
标准协议：完全符合 MCP 规范，可与任何 MCP 客户端集成

快速开始

方式一：使用 uvx 运行（推荐）

无需安装，直接运行：

# 设置 API 密钥并启动服务
GEMINI_API_KEY=your-api-key uvx gemini-mcp

方式二：通过 pip 安装

# 安装包
pip install gemini-mcp

# 运行服务
GEMINI_API_KEY=your-api-key gemini-mcp

方式三：从源码运行

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

# 安装依赖
pip install -r requirements.txt

# 运行服务
python -m gemini_mcp

客户端配置

Claude Desktop 配置

打开配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
添加以下配置：

{
  "mcpServers": {
    "gemini": {
      "command": "uvx",
      "args": ["gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor 配置

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gemini": {
      "command": "uvx",
      "args": ["gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

使用示例

在配置好的 Claude Desktop 或 Cursor 中，你可以：

# 分析本地图片
请分析这张图片：/Users/name/Pictures/photo.jpg

# 分析网络图片
描述一下这个图片的内容：https://example.com/image.png

# 提取图片中的文字
提取图片中的所有文字：/path/to/document.png

# 场景理解
这张图片是在什么场景下拍摄的？/path/to/scene.jpg

高级配置

环境变量

变量名	说明	默认值
`GEMINI_API_KEY`	Gemini API 密钥（必需）	-
`OUTPUT_DIR`	输出文件保存目录	`./outputs`
`ALL_PROXY`	SOCKS5 代理地址	-
`LOG_LEVEL`	日志级别	`INFO`

命令行参数

# 查看所有可用参数
gemini-mcp --help

# 以 HTTP 服务模式运行
gemini-mcp --mode http --port 8080

# 启用调试模式
gemini-mcp --debug

# 指定输出目录
gemini-mcp --output-dir /custom/path

API 参考

支持的工具

`analyze_image`

分析图片内容并返回描述。

参数：

image_input: 图片输入（文件路径、URL 或 Base64）
prompt: 分析提示词（可选）

示例：

{
  "tool": "analyze_image",
  "arguments": {
    "image_input": "/path/to/image.jpg",
    "prompt": "描述这张图片中的主要内容"
  }
}

开发指南

本地开发

# 克隆项目
git clone https://github.com/chengfeng2025/gemini-mcp-python.git
cd gemini-mcp-python

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

贡献代码

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

故障排除

常见问题

Q: 提示 "API key not found" A: 确保已正确设置 GEMINI_API_KEY 环境变量。

Q: 连接超时错误 A: 检查网络连接，或配置代理：

ALL_PROXY=socks5://127.0.0.1:1080 gemini-mcp

Q: Claude Desktop 无法识别服务 A: 重启 Claude Desktop 应用以重新加载配置。

项目信息

作者: chengfeng2025
许可证: MIT
版本: 1.0.0
更新时间: 2025年1月
GitHub: gemini-mcp-python

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

注意：使用本项目需要有效的 Gemini API 密钥。

API 密钥获取方式

官方渠道：访问 Google AI Studio 获取官方密钥（需要科学上网）
兔子 API：访问兔子API充值平台购买兼容官方格式的 API 服务（国内直连，无需梯子，完全兼容 Gemini 官方 API 接口）