Image Compare Server

MCP图像比较服务器

](https://www.npmjs.com/package/mcp-image-compare-server)  ](https://nodejs.org)

越南语 | 英文

一种用于像素级精确图像比较的模型上下文协议（MCP）服务器 像素匹配 来自Mapbox。比较图像、捕获并对比截图，精准检测视觉差异。

特点/功能

• 🎯（瞄准靶心） 像素级精确对比 - 检测出单个像素的差异
• 🎨 表示艺术创作或绘画的符号，可译为“🎨（艺术/绘画）”。 感知色差 - YIQ色彩空间，实现类人感知
• 🔍（放大镜图标，通常表示搜索或查看细节） 抗锯齿检测 - 智能检测并排除抗锯齿像素
• 📊（图表/数据表格） 详细统计 - 像素数量、百分比、尺寸
• 🖼️（表示图片的符号，可译为“图片”或“图像”） 视觉差异输出 - 彩色编码差异可视化
• 🌐（这个符号本身在中文中没有直接对应的翻译，它通常表示“互联网”或“全球网络”的意思，可以理解为“网络”或“互联网”的象征） 网页截图支持 - 与实时网站进行比较
• 📁 文件夹 多种格式 - 支持PNG和JPEG格式
• ⚡（闪电符号，无直接对应中文翻译，常用于表示速度、活力或电力等概念） 快速且轻便 - 包大小约60-80KB

快速入门

安装

# Install globally
npm install -g mcp-image-compare-server

# Install Chromium for screenshots
npx playwright install chromium

配置

对于Claude Desktop

在你的Claude Desktop配置文件中添加：

Windows： %APPDATA%\Claude\claude_desktop_config.json\ macOS： ~/Library/Application Support/Claude/claude_desktop_config.json\ Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "image-compare": {
      "command": "npx",
      "args": ["-y", "mcp-image-compare-server"]
    }
  }
}

配置完成后重启Claude桌面版。

为Cursor（注：Cursor可能是一个特定的软件、项目或概念的名称，根据上下文可能需要具体翻译，但在此处直接保留原样以保持通用性）

在您的Cursor MCP设置文件中添加：

Windows： %APPDATA%\Cursor\User\globalStorage\mcp.json\ macOS: ~/Library/Application Support/Cursor/User/globalStorage/mcp.json\ Linux： ~/.config/Cursor/User/globalStorage/mcp.json

{
  "mcpServers": {
    "image-compare": {
      "command": "npx",
      "args": ["-y", "mcp-image-compare-server"]
    }
  }
}

或者通过Cursor设置：

1. 打开光标设置（Ctrl+, 或者 Cmd+,）
2. 搜索“MCP”
3. 点击“在 settings.json 中编辑”
4. 添加上述配置

配置完成后重启光标。

使用方法

在Claude Desktop或Cursor中询问：

Compare image1.png and image2.png

就是这个！ 🎉

工具

1. 比较图像

比较两个本地图像文件。

参数：

• image1_path （字符串，必填）- 第一张图片的路径
• image2_path （字符串，必填）- 第二张图像的路径
• diff_output_path (字符串，可选) - 保存差异图像的位置
• threshold （数字，可选）- 比较阈值（0-1），默认值为0.1
• includeAA (布尔型，可选) - 是否包含抗锯齿像素，默认为否

示例：

{
  "image1_path": "./screenshots/before.png",
  "image2_path": "./screenshots/after.png",
  "diff_output_path": "./diff-result.png",
  "threshold": 0.1
}

2. 用URL比较图像

将本地图像与来自URL的截图进行比较。

参数：

• image_path （字符串，必填）- 本地图像路径
• url （字符串，必填）- 用于捕获和比较的URL
• diff_output_path (字符串，可选) - 保存差异图像的位置
• threshold （数字，可选）- 比较阈值（0-1），默认值为0.1
• includeAA (布尔值，可选) - 包含抗锯齿像素，默认为false

示例：

{
  "image_path": "./design-mockup.png",
  "url": "https://example.com",
  "threshold": 0.15
}

3. 比较网址（或网址对比）

比较来自两个不同网址的截图。

参数：

• url1 （字符串，必填）- 要捕获的第一个URL
• url2 (字符串，必填) - 要捕获的第二个URL
• diff_output_path （字符串，可选）- 保存差异图像的位置
• threshold （数字，可选）- 比较阈值（0-1），默认值为0.1
• includeAA (布尔值，可选) - 是否包含抗锯齿像素，默认为 false

示例：

{
  "url1": "https://staging.example.com",
  "url2": "https://production.example.com"
}

输出格式

所有工具均返回包含详细统计数据的JSON：

{
  "success": true,
  "diffPixels": 1234,
  "totalPixels": 921600,
  "percentDiff": 0.13,
  "width": 1280,
  "height": 720,
  "diffImagePath": "/path/to/diff.png",
  "message": "Comparison completed: 1234 pixels differ (0.13%)"
}

字段：

• success - 运行状态（真/假）
• diffPixels - 不同像素的数量
• totalPixels - 图像中的总像素数
• percentDiff - 百分比差异
• width - 图像宽度（以像素为单位）
• height - 图像高度（以像素为单位）
• diffImagePath - 生成的差异图像的路径
• message - 人类可读的结果消息
• error - 错误信息（如失败时）

用例

视觉回归测试

比较更新前后的用户界面，以捕捉意外的更改。

I have two screenshots:
- before-update.png
- after-update.png

Compare them and tell me what changed.

跨浏览器测试

比较不同浏览器的渲染效果，以确保一致性。

设计评审

将设计样稿与实际实现进行对比。

Compare design-mockup.png with https://myapp.com/landing

A/B测试

比较同一页面的不同版本。

Compare:
- https://myapp.com/variant-a
- https://myapp.com/variant-b

移动设备与台式设备

比较不同视口下的响应式布局。

配置

阈值

这个（或“该”） threshold 参数（0-1）控制比较灵敏度：

• 0.0 - 非常敏感，能检测到最小的差异
• 0.1 - 默认设置，适用于大多数情况的良好平衡
• 0.3 - 不那么敏感，忽略细微差异
• 1.0 - 最不敏感，仅显示主要差异

抗锯齿处理

当 includeAA = false （默认设置），服务器会自动检测并忽略抗锯齿像素，从而减少来自不同渲染引擎的误报。

差异图像颜色

• 红色不同的像素
• 黄色抗锯齿像素（如果 includeAA = true）
• 褪色匹配像素（降低不透明度）

安装方法

方法1：NPM全局（推荐）

npm install -g mcp-image-compare-server
npx playwright install chromium

配置Claude桌面版：

{
  "command": "npx",
  "args": ["-y", "mcp-image-compare-server"]
}

方法2：NPX（无需安装）

配置Claude桌面版：

{
  "command": "npx",
  "args": ["-y", "mcp-image-compare-server"]
}

首次运行时会自动下载该程序包。

方法3：从源（处）

git clone https://github.com/leky90/mcp-image-compare-server.git
cd mcp-image-compare-server
npm install
npx playwright install chromium
npm run build

配置Claude桌面版或Cursor：

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-image-compare-server/dist/index.js"]
}

替换 /absolute/path/to/mcp-image-compare-server 根据你实际的路径。

系统要求

• Node.js： 18.0.0 或更高版本
• npm:（此处为专有名词，通常不直接翻译，保持原样）npm（Node Package Manager） 8.0.0或更高版本
• 操作系统： Windows 10及以上版本，macOS 10.15及以上版本，Linux（Ubuntu 20.04及以上版本）
• 磁盘： 约500MB（包含Chromium浏览器）
• RAM：随机存取存储器 最低2GB

故障排除

服务器无法连接

1. 验证配置路径是否正确
2. 确保你已经运行了 npm run build
3. 完全重启Claude桌面版或Cursor
4. 检查MCP日志中的错误

“未找到浏览器”错误

npx playwright install chromium

截图超时

对于加载缓慢的网站，默认的30秒超时设置将处理大多数情况。如果问题仍然存在，请报告。

内存不足

对于非常大的图像：

• 在比较之前调整图像大小
• 使用较低分辨率的图像
• 增加 Node.js 内存： node --max-old-space-size=4096 dist/index.js

发展

从源代码构建

npm install
npm run build

本地运行

npm start
# or
npm run dev

测试

看 \CONTRIBUTING.md\ 翻译为中文是：“贡献指南/贡献规范文件”。这个文件通常用于说明如何向项目做出贡献，包括代码提交规范、问题报告流程、代码风格要求等 作为开发指南。

技术栈

• 框架： 模型上下文协议SDK
• 图像对比： 像素匹配
• 截图： 剧作家
• 语言： TypeScript

贡献

欢迎投稿！请阅读 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “如何贡献.md”（具体翻译可能根据上下文略有调整，但大意相同）。这里，“CONTRIBUTING”通常指的是关于如何向项目做出贡献的指南或说明，“.md”表示这是一个Markdown格式的文件 作为指南。

更改日志

见 CHANGELOG.md 翻译为中文是：“版本更新日志文件（Markdown 格式）” 用于版本历史。

许可证

MIT 许可证 - 详见 许可证 文件中有详细信息。

致谢

构建于：

• 像素匹配 由Mapbox提供
• 模型上下文协议
• 剧作家
• 夏普

支持

• 🐛 表示“虫子”或“错误（bug）”（在计算机领域常用） 错误报告：
• 💬 问题：
• 📖 一本书 文档： 这个README文件

______________________________________________________________________

用 TypeScript 和 MCP 充满爱意地打造