Ai Vision MCP

🚀 AI视觉MCP服务器

这是一个强大的模型上下文协议（MCP）服务器，借助谷歌Gemini和Vertex AI模型，提供基于人工智能的图像和视频分析功能。

🚀 快速开始

前提条件

你可以选择使用google 提供商或 vertex_ai 提供商。为简便起见，建议使用 google 提供商。

以下是根据你所选提供商需要设置的环境变量。（注意：建议将MCP客户端的超时配置设置为超过5分钟。）

(i) 使用谷歌AI工作室提供商

export IMAGE_PROVIDER="google" # 或 vertex_ai
export VIDEO_PROVIDER="google" # 或 vertex_ai
export GEMINI_API_KEY="your-gemini-api-key"

你可以在此处获取谷歌AI工作室的API密钥。

(ii) 使用Vertex AI提供商

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

有关如何设置的具体指南，请参考此处。

安装

以下是在不同MCP客户端（如Claude Desktop、Claude Code、Cursor、Cline等）上安装此MCP的指南。

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=google \
  -e VIDEO_PROVIDER=google \
  -e GEMINI_API_KEY=your-gemini-api-key \
  -- npx ai-vision-mcp

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=vertex_ai \
  -e VIDEO_PROVIDER=vertex_ai \
  -e VERTEX_CREDENTIALS=/path/to/service-account.json \
  -e GCS_BUCKET_NAME=ai-vision-mcp-{VERTEX_PROJECT_ID} \
  -- npx ai-vision-mcp

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

{
  "mcpServers": {
    "timeout": 300, 
    "type": "stdio",
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "timeout": 300,
      "type": "stdio",
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

npx ai-vision-mcp

✨ 主要特性

• 双提供商支持：可在谷歌Gemini API和Vertex AI之间进行选择。
• 多模态分析：支持图像和视频内容分析。
• 灵活的文件处理：支持通过多种方式（URL、本地文件、Base64）上传。
• 存储集成：内置谷歌云存储支持。
• 全面验证：全程使用基于Zod的数据验证。
• 错误处理：具备强大的错误处理机制，包含重试逻辑和熔断机制。
• TypeScript支持：完全支持TypeScript，并进行严格的类型检查。

💻 使用示例

基础用法

服务器提供了四个主要的MCP工具，以下是这些工具的使用示例：

1) analyze_image

使用人工智能分析图像，并返回详细描述。 参数：

• imageSource（字符串）：图像的URL、Base64数据或文件路径。
• prompt（字符串）：向人工智能提出的问题或指令。
• options（对象，可选）：分析选项，包括温度和最大令牌数。

示例：

{
  "imageSource": "https://plus.unsplash.com/premium_photo-1710965560034-778eedc929ff",
  "prompt": "这张图片是关于什么的？详细描述你看到的内容。"
}

2) compare_images

使用人工智能比较多张图像，并返回详细的比较分析结果。 参数：

• imageSources（数组）：图像源数组（URL、Base64数据或文件路径），最少2张，最多4张图像。
• prompt（字符串）：用于比较图像的问题或指令。
• options（对象，可选）：分析选项，包括温度和最大令牌数。

示例：

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "prompt": "比较这两张图片，并告诉我它们的区别。"
}

3) detect_objects_in_image

使用人工智能视觉模型检测图像中的物体，并生成带有边界框的注释图像。返回带有坐标的检测物体，并将注释图像保存到文件或临时目录。 参数：

• imageSource（字符串）：图像的URL、Base64数据或文件路径。
• prompt（字符串）：自定义检测提示，描述要在图像中检测或识别的内容。
• outputFilePath（字符串，可选）：注释图像的显式输出路径。

配置： 此函数使用优化的默认参数进行物体检测，不接受运行时 options 参数。要自定义人工智能参数（温度、topP、topK、最大令牌数），请使用环境变量：

# 推荐的物体检测环境变量设置（这些现在是默认值）
TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0     # 确定性响应
TOP_P_FOR_DETECT_OBJECTS_IN_IMAGE=0.95          # 核采样
TOP_K_FOR_DETECT_OBJECTS_IN_IMAGE=30            # 词汇选择
MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192     # 高令牌限制，用于JSON

文件处理逻辑：

1. 提供显式输出文件路径 → 保存到指定的精确路径。
2. 未提供显式输出文件路径 → 自动保存到临时目录。

响应类型：

• 提供显式输出文件路径时，返回 file 对象。
• 未提供显式输出文件路径时，返回 tempFile 对象，图像文件输出自动保存到临时文件夹。
• 始终包含 detections 数组，其中包含检测到的物体和坐标。
• 包含 summary，其中包含基于百分比的坐标，用于浏览器自动化。

示例：

{
  "imageSource": "https://example.com/image.jpg",
  "prompt": "检测这张图片中的所有物体。"
}

4) analyze_video

使用人工智能分析视频，并返回详细描述。 参数：

• videoSource（字符串）：视频的YouTube URL、GCS URI或本地文件路径。
• prompt（字符串）：向人工智能提出的问题或指令。
• options（对象，可选）：分析选项，包括温度和最大令牌数。

支持的视频源：

• YouTube URL（例如：https://www.youtube.com/watch?v=...）
• 本地文件路径（例如：C:\Users\username\Downloads\video.mp4）

示例：

{
  "videoSource": "https://www.youtube.com/watch?v=9hE5-98ZeCg",
  "prompt": "这个视频是关于什么的？详细描述你看到的内容。"
}

📚 详细文档

环境配置

对于基本设置，你只需配置提供商选择和所需的凭证：

谷歌AI工作室提供商（推荐）

export IMAGE_PROVIDER="google"
export VIDEO_PROVIDER="google"
export GEMINI_API_KEY="your-gemini-api-key"

Vertex AI提供商（生产环境）

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

📖 详细配置指南

有关全面的环境变量文档，包括：

• 完整的配置参考（60多个环境变量）
• 特定功能的优化示例
• 高级配置模式
• 故障排除指南

👉 查看环境变量指南

配置优先级概述

服务器使用分层配置系统，更具体的设置会覆盖通用设置：

1. 大语言模型分配的值（工具调用中的运行时参数）
2. 特定功能变量（TEMPERATURE_FOR_ANALYZE_IMAGE 等）
3. 特定任务变量（TEMPERATURE_FOR_IMAGE 等）
4. 通用变量（TEMPERATURE 等）
5. 系统默认值

# 通用设置
export TEMPERATURE=0.7
export MAX_TOKENS=1500

# 特定任务优化
export TEMPERATURE_FOR_IMAGE=0.2     # 图像更精确
export TEMPERATURE_FOR_VIDEO=0.5     # 视频更具创造性

# 优化单个功能
export TEMPERATURE_FOR_ANALYZE_IMAGE=0.1
export TEMPERATURE_FOR_COMPARE_IMAGES=0.3
export TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0  # 确定性
export MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192   # 高令牌限制

# 为每个功能选择模型
export ANALYZE_IMAGE_MODEL="gemini-2.5-flash-lite"
export COMPARE_IMAGES_MODEL="gemini-2.5-flash"
export ANALYZE_VIDEO_MODEL="gemini-2.5-flash-pro"

开发

前提条件

• Node.js 18+
• npm 或 yarn

设置

# 克隆仓库
git clone https://github.com/tan-yong-sheng/ai-vision-mcp.git
cd ai-vision-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 启动开发服务器
npm run dev

脚本

• npm run build - 构建TypeScript项目。
• npm run dev - 以监视模式启动开发服务器。
• npm run lint - 运行ESLint。
• npm run format - 使用Prettier格式化代码。
• npm start - 启动已构建的服务器。

架构

项目采用模块化架构：

src/
├── providers/          # AI提供商实现
│   ├── gemini/        # 谷歌Gemini提供商
│   ├── vertexai      # Vertex AI提供商
│   └── factory/       # 提供商工厂
├── services/          # 核心服务
│   ├── ConfigService.ts
│   └── FileService.ts
├── storage/           # 存储实现
├── file-upload/       # 文件上传策略
├── types/            # TypeScript类型定义
├── utils/            # 实用函数
└── server.ts         # 主MCP服务器

错误处理

服务器包含全面的错误处理机制：

• 验证错误：使用Zod模式进行输入验证。
• 网络错误：使用指数退避进行自动重试。
• 身份验证错误：针对API密钥问题提供清晰的错误消息。
• 文件错误：处理文件大小限制和格式限制。

🔧 技术细节

配置优先级

服务器采用分层配置系统，具体优先级如下：

这种分层配置系统确保了更具体的设置能够覆盖通用设置，从而提供了灵活的配置选项。

错误处理机制

服务器具备强大的错误处理能力，针对不同类型的错误采取了相应的处理策略：

• 验证错误：使用Zod模式对输入数据进行验证，确保数据的有效性。如果输入数据不符合预期格式，将抛出明确的验证错误信息。
• 网络错误：采用指数退避算法进行自动重试，以应对临时的网络问题。当发生网络错误时，服务器会自动重试请求，重试间隔会随着重试次数的增加而指数级增长，直到达到最大重试次数或请求成功。
• 身份验证错误：对于API密钥问题，服务器会返回清晰的错误消息，帮助用户快速定位和解决身份验证问题。
• 文件错误：在处理文件上传和存储时，服务器会处理文件大小限制和格式限制等问题。如果文件大小超过限制或文件格式不支持，服务器会返回相应的错误信息。

模块化架构设计

项目采用模块化架构，将不同的功能模块进行分离，提高了代码的可维护性和可扩展性。主要模块包括：

• providers：负责实现不同的AI提供商，如谷歌Gemini和Vertex AI。每个提供商都有独立的实现，通过工厂模式进行管理，方便切换和扩展。
• services：包含核心服务，如配置服务和文件服务。这些服务提供了统一的接口，供其他模块调用。
• storage：实现了存储功能，与谷歌云存储集成，确保数据的安全存储和高效访问。
• file-upload：处理文件上传相关的逻辑，支持多种上传方式，如URL、本地文件和Base64编码。
• types：定义了TypeScript类型，确保代码的类型安全。
• utils：提供了各种实用函数，供其他模块复用。
• server：作为主MCP服务器，负责接收和处理请求，协调各个模块的工作。

通过这种模块化架构，项目的各个部分可以独立开发、测试和维护，同时也方便了新功能的添加和现有功能的优化。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

致谢

• 感谢谷歌提供的Gemini和Vertex AI API。
• 感谢模型上下文协议团队提供的MCP框架。
• 感谢本项目的所有贡献者和用户。