金大哥 - ai-vision-mcp MCP 详情

article

README

🚀 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的指南。

Claude Desktop

将以下内容添加到你的Claude Desktop配置中：

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

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

(ii) 使用Vertex AI提供商

{
  "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 Code

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

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

(ii) 使用Vertex AI提供商

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

注意：通过更新 ~\.claude\settings.json 文件，将MCP启动超时时间增加到1分钟，MCP工具执行超时时间增加到约5分钟，如下所示：

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

Cursor

操作步骤：设置 -> Cursor设置 -> MCP -> 添加新的全局MCP服务器。

建议将以下配置粘贴到你的Cursor ~/.cursor/mcp.json 文件中。你也可以通过在项目文件夹中创建 .cursor/mcp.json 文件，将其安装到特定项目中。更多信息请参阅 Cursor MCP文档。

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

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

(ii) 使用Vertex AI提供商

{
  "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}"
      }
    }
  }
}

Cline

Cline使用JSON配置文件来管理MCP服务器。要集成提供的MCP服务器配置，请按以下步骤操作：

打开Cline，点击顶部导航栏中的MCP服务器图标。
选择“已安装”选项卡，然后点击“高级MCP设置”。
在 cline_mcp_settings.json 文件中添加以下配置：

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

{
  "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"
      }
    }
  }
}

(ii) 使用Vertex AI提供商

{
  "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}"
      }
    }
  }
}

其他MCP客户端

该服务器使用标准输入输出传输，并遵循标准MCP协议。通过运行以下命令，可将其与任何兼容MCP的客户端集成：

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

文件处理逻辑：

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

响应类型：

提供显式输出文件路径时，返回 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多个环境变量）
特定功能的优化示例
高级配置模式
故障排除指南

👉 查看环境变量指南

配置优先级概述

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

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

快速配置示例

基本优化：

# 通用设置
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密钥问题提供清晰的错误消息。
文件错误：处理文件大小限制和格式限制。

🔧 技术细节

配置优先级

服务器采用分层配置系统，具体优先级如下： | 优先级 | 配置类型 | 说明 | | ---- | ---- | ---- | | 1 | 大语言模型分配的值 | 工具调用中的运行时参数 | | 2 | 特定功能变量 | 如 TEMPERATURE_FOR_ANALYZE_IMAGE 等 | | 3 | 特定任务变量 | 如 TEMPERATURE_FOR_IMAGE 等 | | 4 | 通用变量 | 如 TEMPERATURE 等 | | 5 | 系统默认值 | 服务器内置的默认配置 |

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

错误处理机制

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

验证错误：使用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框架。
感谢本项目的所有贡献者和用户。

ai-vision-mcp

README

🚀 AI视觉MCP服务器

🚀 快速开始

前提条件

安装

✨ 主要特性

💻 使用示例

基础用法

1) `analyze_image`

2) `compare_images`

3) `detect_objects_in_image`

4) `analyze_video`

📚 详细文档

环境配置

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

Vertex AI提供商（生产环境）

📖 详细配置指南

配置优先级概述

开发

前提条件

设置

脚本

架构

错误处理

🔧 技术细节

配置优先级

错误处理机制

模块化架构设计

📄 许可证

致谢

运行方式说明

托管运行

本地运行 / 其它方式

ai-vision-mcp

README

🚀 AI视觉MCP服务器

🚀 快速开始

前提条件

安装

✨ 主要特性

💻 使用示例

基础用法

1) analyze_image

2) compare_images

3) detect_objects_in_image

4) analyze_video

📚 详细文档

环境配置

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

Vertex AI提供商（生产环境）

📖 详细配置指南

配置优先级概述

开发

前提条件

设置

脚本

架构

错误处理

🔧 技术细节

配置优先级

错误处理机制

模块化架构设计

📄 许可证

致谢

运行方式说明

托管运行

本地运行 / 其它方式

1) `analyze_image`

2) `compare_images`

3) `detect_objects_in_image`

4) `analyze_video`