tan-yong-sheng/ai-vision-mcp

分类Search

作者Community

星标853

定价Free

简介

ai-vision-mcp 是一个让 AI 具备“视觉分析能力”的 MCP 服务端，它通过集成 Google Gemini 和 Vertex AI，将多模态视觉识别能力直接接入你的 AI 客户端。不同于简单的图片描述，它更侧重于实用的工程场景，比如 UI/UX 界面走查、视觉回归测试以及复杂的界面元素理解。对于开发者而言，这意味着你无需在多个平台间切换，直接在对话界面就能让 AI 帮你分析截图或视频中的 UI 问题。上手难度较低，只要配置好 API Key 即可快速集成到支持 MCP 的编辑器或客户端中。

核心亮点

集成 Gemini 多模态能力，支持图文及视频分析
精准识别 UI 元素，适用于界面走查与 UX 评估
支持视觉回归测试，自动化检测界面变更
通过 MCP 协议无缝接入 IDE，提升开发调试效率

完整文档

AI Vision MCP Server

一个强大的 Model Context Protocol (MCP) 服务器，利用 Google Gemini 和 Vertex AI 模型提供 AI 驱动的图像和视频分析。

Features

双提供商支持：可在 Google Gemini API 和 Vertex AI 之间选择

多模态分析：支持图像和视频内容的分析

灵活的文件处理：支持多种上传方式（URL、本地文件、base64）

存储集成：内置 Google Cloud Storage 支持

全面验证：全程基于 Zod 的数据验证

错误处理：具备重试逻辑和熔断机制的鲁棒错误处理

TypeScript：完整的 TypeScript 支持及严格类型检查

Quick Start

Pre-requisites

您可以选择使用 google provider 或 vertex_ai provider。为了简单起见，推荐使用 google provider。

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

(i) 使用 Google AI Studio Provider

bash

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

在此处 here 获取你的 Google AI Studio 的 api key

(ii) 使用 Vertex AI Provider

bash

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CLIENT_EMAIL="[email protected]"
export VERTEX_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
export VERTEX_PROJECT_ID="your-gcp-project-id"
export GCS_BUCKET_NAME="your-gcs-bucket"

请参考此处的指南了解如何进行设置。

安装

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

<details>
<summary>Claude Desktop</summary>

添加到您的 Claude Desktop 配置中：

(i) 使用 Google AI Studio Provider

json

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

json

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CLIENT_EMAIL": "[email protected]",
        "VERTEX_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
        "VERTEX_PROJECT_ID": "your-gcp-project-id",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

</details>

<details>
<summary>Claude Code</summary>

(i) 使用 Google AI Studio Provider

bash

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 Provider

bash

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=vertex_ai \
  -e VIDEO_PROVIDER=vertex_ai \
  -e VERTEX_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com \
  -e VERTEX_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" \
  -e VERTEX_PROJECT_ID=your-gcp-project-id \
  -e GCS_BUCKET_NAME=ai-vision-mcp-{VERTEX_PROJECT_ID} \
  -- npx ai-vision-mcp

注意：通过按如下方式更新 ~\.claude\settings.json，将 MCP 启动超时时间增加至 1 分钟，并将 MCP 工具执行超时时间增加至约 5 分钟：

json

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

</details>

<details>
<summary>Cursor</summary>

前往：Settings -> Cursor Settings -> MCP -> Add new global MCP server

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

(i) 使用 Google AI Studio Provider

json

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

json

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CLIENT_EMAIL": "[email protected]",
        "VERTEX_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
        "VERTEX_PROJECT_ID": "your-gcp-project-id",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

</details>

<details>
<summary>Cline</summary>

Cline 使用 JSON 配置文件来管理 MCP 服务器。要集成提供的 MCP 服务器配置：

1. 打开 Cline，点击顶部导航栏中的 MCP Servers 图标。
2. 选择 Installed 选项卡，然后点击 Advanced MCP Settings。
3. 在 cline_mcp_settings.json 文件中，添加以下配置：

(i) 使用 Google AI Studio Provider

json

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

json

{
  "mcpServers": {
    "ai-vision-mcp": {
      "timeout": 300,
      "type": "stdio",
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CLIENT_EMAIL": "[email protected]",
        "VERTEX_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
        "VERTEX_PROJECT_ID": "your-gcp-project-id",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

</details>

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

bash

npx ai-vision-mcp

</details>

MCP Tools

该服务器提供四个主要的 MCP tools：

1) `analyze_image`

使用 AI 分析图像并返回详细描述。

Parameters:

imageSource (string): 图像的 URL、base64 数据或文件路径

prompt (string): 给 AI 的问题或指令

mode (string, optional): 分析模式 - 可选值：

- general (默认) - 通用图像分析
- palette - 提取 design tokens（颜色、间距、排版）
- hierarchy - 分析视觉层级和视觉流向
- components - 编目 UI components 和设计系统成熟度

options (object, optional): 分析选项，包括 temperature 和 max tokens

Examples:

1. General image analysis:

json

{
  "imageSource": "https://plus.unsplash.com/premium_photo-1710965560034-778eedc929ff",
  "prompt": "What is this image about? Describe what you see in detail."
}

2. 提取 design tokens：

json

{
  "imageSource": "https://example.com/design.png",
  "prompt": "Extract all design tokens from this screenshot",
  "mode": "palette"
}

3. 分析视觉层级：

json

{
  "imageSource": "C:\\Users\\username\\Downloads\\ui_mockup.png",
  "prompt": "Analyze the visual hierarchy and eye flow",
  "mode": "hierarchy"
}

4. 组件清单：

json

{
  "imageSource": "https://example.com/design-system.png",
  "prompt": "List all UI components and evaluate design system maturity",
  "mode": "components"
}

### 2) compare_images

使用 AI 比较多张图像并返回详细的对比分析。

参数：

imageSources (array)：图像源数组（URL、base64 数据或文件路径）- 最少 2 张，最多 4 张图像

prompt (string)：用于比较图像的问题或指令

options (object, optional)：分析选项，包括 temperature 和 max tokens

示例：

1. 比较来自 URL 的图像：

json

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "prompt": "Compare these two images and tell me the differences"
}

2. 比较混合源：

json

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "C:\\\\Users\\\\username\\\\Downloads\\\\image2.jpg",
    "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
  ],
  "prompt": "Which image has the best lighting quality?"
}

### 3) detect_objects_in_image

使用 AI 视觉模型检测图像中的对象，并生成带有边界框的标注图像。返回检测到的对象及其坐标，并将标注后的图像保存到文件或临时目录中。

参数：

imageSource (string)：图像的 URL、base64 数据或文件路径

prompt (string)：自定义检测提示词，用于描述需要检测或识别的内容

outputFilePath (string, 可选)：标注图像的明确输出路径

配置：
该函数使用针对对象检测优化的默认参数，不接受运行时 options 参数。如需自定义 AI 参数（temperature, topP, topK, maxTokens），请使用环境变量：

code

# Recommended environment variable settings for object detection (these are now the defaults)
TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0     # Deterministic responses
TOP_P_FOR_DETECT_OBJECTS_IN_IMAGE=0.95          # Nucleus sampling
TOP_K_FOR_DETECT_OBJECTS_IN_IMAGE=30            # Vocabulary selection
MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192     # High token limit for JSON

文件处理逻辑：
1. 提供了明确的 outputFilePath → 保存到指定的精确路径
2. 未提供明确的 outputFilePath → 自动保存到临时目录

响应类型：

当提供明确的 outputFilePath 时，返回 file 对象

当未提供明确的 outputFilePath 时，返回 tempFile 对象，图像文件输出将自动保存到临时文件夹

始终包含带有检测对象和坐标的 detections 数组

包含带有基于百分比坐标的 summary，用于浏览器自动化

示例：

1. 基础对象检测：

json

{
  "imageSource": "https://example.com/image.jpg",
  "prompt": "Detect all objects in this image"
}

2. 将标注后的图像保存到指定路径：

json

{
  "imageSource": "C:\\Users\\username\\Downloads\\image.jpg",
  "outputFilePath": "C:\\Users\\username\\Documents\\annotated_image.png"
}

3. 自定义检测提示词 (Custom detection prompt)：

json

{
  "imageSource": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB...",
  "prompt": "Detect and label all electronic devices in this image"
}

### 4) audit_design

通过像素级分析和 AI 评审，审计 UI/UX 设计的合规性。

该工具利用纯 TypeScript/JavaScript 像素分析结合 Gemini Vision API 评审，提供自动化的设计合规性审计。它可以提取主导颜色、检测视觉复杂度、验证 WCAG 对比度，并生成可操作的设计建议。

灵感来自： Jade Graham 的 Automating UX/UI Design Analysis with Python, Machine Learning, and LLMs

参数：

imageSource (string)：设计图片的 URL、base64 数据或文件路径

prompt (string, 可选)：自定义审计上下文或重点关注区域

options (object, 可选)：分析选项，包括 temperature 和 max tokens

特性：

Dominant Colors：使用 K-means 聚类提取 5 种主导颜色

Edge Complexity：使用 Sobel 算子进行视觉结构分析

WCAG Contrast：基于 W3C 相对亮度公式验证 (AA/AAA)

Luminance Stats：计算平均亮度及标准差

Design Issues：自动检测对比度、复杂度及亮度问题

AI Critique：由 Gemini 提供设计改进建议

示例：

1. 基础设计审计：

json

{
  "imageSource": "https://example.com/design.png",
  "prompt": "Audit this design for accessibility and visual hierarchy"
}

2. 审计本地设计文件：

json

{
  "imageSource": "C:\\Users\\username\\Downloads\\ui_design.png",
  "prompt": "Check WCAG AA compliance"
}

### 5) analyze_video

使用 AI 分析视频并返回详细描述。

参数：

videoSource (string)：YouTube URL、GCS URI 或视频的本地文件路径

prompt (string)：给 AI 的问题或指令

options (object, 可选)：分析选项，包括 temperature 和 max tokens

支持的视频来源：

YouTube URLs (例如：https://www.youtube.com/watch?v=...)

本地文件路径 (例如：C:\Users\username\Downloads\video.mp4)

示例：

1. 分析来自 YouTube URL 的视频：

json

{
  "videoSource": "https://www.youtube.com/watch?v=9hE5-98ZeCg",
  "prompt": "What is this video about? Describe what you see in detail."
}

2. 分析本地视频文件：

json

{
  "videoSource": "C:\\Users\\username\\Downloads\\video.mp4",
  "prompt": "What is this video about? Describe what you see in detail."
}

注意： 公开视频 URL 仅支持 YouTube URL。目前不支持其他公开视频 URL。

环境配置

对于基础设置，您只需要配置 provider 选择和必要的凭据：

Google AI Studio Provider (推荐)

bash

export IMAGE_PROVIDER="google"


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

### Vertex AI Provider (生产环境)

bash

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CLIENT_EMAIL="[email protected]"
export VERTEX_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
export VERTEX_PROJECT_ID="your-gcp-project-id"
export GCS_BUCKET_NAME="your-gcs-bucket"

### 📖 详细配置指南

如需查看完整的环境变量文档，包括：

完整的配置参考（60+ 个环境变量）

特定功能的优化示例

高级配置模式

故障排除指南

👉 查看环境变量指南

配置优先级概览

服务器采用分层配置系统，具体设置将覆盖通用设置：

1. LLM 分配的值（tool calls 中的运行时参数）
2. 特定功能变量（如 TEMPERATURE_FOR_ANALYZE_IMAGE 等）
3. 特定任务变量（如 TEMPERATURE_FOR_IMAGE 等）
4. 通用变量（如 TEMPERATURE 等）
5. 系统默认值

<details>
<summary><strong>快速配置示例</strong></summary>

基础优化：

bash

# General settings
export TEMPERATURE=0.7
export MAX_TOKENS=1500
Task-specific optimization
export TEMPERATURE_FOR_IMAGE=0.2     # More precise for images
export TEMPERATURE_FOR_VIDEO=0.5     # More creative for videos

特定功能的优化：

bash

# Optimize individual functions
export TEMPERATURE_FOR_ANALYZE_IMAGE=0.1
export TEMPERATURE_FOR_COMPARE_IMAGES=0.3
export TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0  # Deterministic
export MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192   # High token limit

模型选择：

bash

# Choose models per function
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"

</details>

故障排除 (stdio / Codex / Claude Code)

1) "Transport closed" / 工具调用失败

如果你看到如下错误：

tools/call failed: Transport closed

常见原因：

A) 图像标注依赖加载失败

此服务器使用 imagescript 进行图像标注/尺寸提取。

验证其是否加载：

bash

npm run doctor
or

npm run check:imagescript

B) stdout 日志破坏 stdio MCP 帧结构

该服务器使用 MCP stdio 传输（基于 stdout 的换行符分隔 JSON-RPC）。

✅ stdout 必须仅包含 MCP JSON-RPC 消息

✅ 将日志写入 stderr（例如 console.error）

❌ 在 stdio MCP 服务器中不要使用 console.log

如果 stdout 被污染，客户端（Codex/Claude Code）可能会断开连接并报告 Transport closed。

Development

Prerequisites

Node.js 18+

npm 或 yarn

Setup

bash

# Clone the repository


git clone https://github.com/tan-yong-sheng/ai-vision-mcp.git
cd ai-vision-mcp
Install dependencies
npm install
Build the project
npm run build
Start development server
npm run dev

tan-yong-sheng/ai-vision-mcp

简介

核心亮点

完整文档

AI Vision MCP Server

Features

Quick Start

Pre-requisites

安装

MCP Tools

1) `analyze_image`

环境配置

Google AI Studio Provider (推荐)
bash
`export IMAGE_PROVIDER="google"`

配置优先级概览

Task-specific optimization

故障排除 (stdio / Codex / Claude Code)

1) "Transport closed" / 工具调用失败

or

Development

Prerequisites

Setup
bash
`# Clone the repository`

Install dependencies

Build the project

Start development server

架构

贡献指南

许可证

致谢

扫码进交流群

tan-yong-sheng/ai-vision-mcp

简介

核心亮点

完整文档

AI Vision MCP Server

Features

Quick Start

Pre-requisites

安装

MCP Tools

1) analyze_image

环境配置

Google AI Studio Provider (推荐)bashexport IMAGE_PROVIDER="google"

配置优先级概览

Task-specific optimization

故障排除 (stdio / Codex / Claude Code)

1) "Transport closed" / 工具调用失败

or

Development

Prerequisites

Setupbash# Clone the repository

Install dependencies

Build the project

Start development server

架构

贡献指南

许可证

致谢

扫码进交流群

1) `analyze_image`

Google AI Studio Provider (推荐)
bash
`export IMAGE_PROVIDER="google"`

Setup
bash
`# Clone the repository`