Sharp MCP

🚀 Sharp MCP

Sharp MCP 是一个用于图像会话管理和处理的 MCP（模型上下文协议）服务器。它提供了在会话中存储图像以及提取图像元数据和颜色的工具，能高效处理多种图像格式。

🚀 快速开始

Sharp MCP 可与支持模型上下文协议（MCP）的各种 AI 编码助手和 IDE 集成。

要求

• Node.js >= v18.0.0
• 兼容 MCP 的客户端（Cursor、Claude Code、VS Code、Windsurf 等）

✨ 主要特性

• create_session：将 Base64 图像存储在具有唯一 ID 的内存会话中。
• create_session_by_path：从图像文件路径创建会话（自动进行 Base64 转换）。
• list_session：列出所有活动的图像会话。
• get_dimensions：获取图像的尺寸和 MIME 类型。
• pick_color：从指定区域提取平均颜色。
• remove_background：使用基于机器学习的分割技术去除图像背景。
• extract_region：从图像中裁剪出一个矩形区域。
• compress_image：压缩图像并进行格式转换（JPEG、PNG、WebP）。
• 采用 TypeScript 构建，确保类型安全。
• 使用 sharp 进行高性能图像处理。

📦 安装指南

NPM

npm install -g sharp-mcp

Smithery

若要通过 Smithery 为任何客户端自动安装 Sharp MCP，请执行以下命令：

npx -y @smithery/cli@latest install sharp-mcp --client <CLIENT_NAME>

可用的客户端有：cursor、claude、vscode、windsurf、cline、zed 等。

📚 详细文档

MCP 客户端集成

Sharp MCP 可与支持模型上下文协议（MCP）的各种 AI 编码助手和 IDE 集成。

{
  "mcpServers": {
    "sharp": {
      "command": "npx",
      "args": ["-y", "sharp-mcp"]
    }
  }
}

claude mcp add sharp -- npx -y sharp-mcp

"mcp": {
  "servers": {
    "sharp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sharp-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sharp": {
      "command": "npx",
      "args": ["-y", "sharp-mcp"]
    }
  }
}

{
  "mcpServers": {
    "sharp": {
      "command": "npx",
      "args": ["-y", "sharp-mcp"]
    }
  }
}

[mcp_servers.sharp]
command = "npx"
args = ["-y", "sharp-mcp"]

可用工具

create_session

使用提供的图像有效负载创建一个新会话，并返回一个唯一的会话 ID。 参数：

• image_payload（字符串，必需）：Base64 编码的图像数据。
• description（字符串，可选）：图像的可选描述。 返回值：

{ "sessionId": "img_abc123xyz" }

示例：

{
  "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
  "description": "首页截图"
}

create_session_by_path

通过从指定的绝对文件路径读取图像来创建一个新会话。自动将文件转换为 Base64 并验证其是否为有效图像。 参数：

• path（字符串，必需）：图像文件的绝对路径。
• description（字符串，可选）：图像的可选描述。 返回值：

{
  "sessionId": "img_abc123xyz",
  "source_path": "/path/to/image.png",
  "file_size": 46849
}

示例：

{
  "path": "/Users/username/images/screenshot.png",
  "description": "首页截图"
}

错误响应：

• 相对路径：路径必须是绝对路径。收到相对路径："./image.png"
• 文件未找到：文件未找到："/path/to/image.png"
• 无效图像：无效或损坏的图像文件："/path/to/file.txt"

list_session

列出所有活动会话及其会话 ID、图像有效负载和描述。 参数：无 返回值：

[
  {
    "sessionId": "img_abc123xyz",
    "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
    "description": "首页截图"
  }
]

get_dimensions

获取存储在会话中的图像的尺寸和 MIME 类型。 参数：

• sessionId（字符串，必需）：create_session 或 create_session_by_path 返回的会话 ID。 返回值：

{
  "width": 1920,
  "height": 1080,
  "mimeType": "image/png"
}

错误响应（无效会话）：

无效或不存在的会话 ID。请先调用 create_session 以获取有效的会话 ID。

pick_color

从以指定坐标为中心的正方形区域中提取平均颜色。 参数：

• sessionId（字符串，必需）：create_session 返回的会话 ID。
• x（数字，必需）：中心点的 X 坐标。
• y（数字，必需）：中心点的 Y 坐标。
• radius（数字，可选，默认值：5）：采样区域的半径。采样区域将是一个大小为（半径 × 2）的正方形。 返回值：

{
  "r": 255,
  "g": 128,
  "b": 64,
  "hex": "#FF8040"
}

错误响应（越界）：

坐标 (2000, 500) 超出图像边界 (1920x1080)。

remove_background

使用基于机器学习的分割技术去除图像的背景。返回带有透明度的 PNG 图像。由 @imgly/background-removal-node 提供支持，可实现准确的主体检测。 参数：

• sessionId（字符串，必需）：create_session 返回的会话 ID。
• output_path（字符串，可选）：保存输出 PNG 文件的绝对路径。如果未提供，则返回 Base64 有效负载。 返回值（无 output_path）：

{
  "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mime_type": "image/png"
}

返回值（有 output_path）：

{
  "path": "/path/to/output.png"
}

示例：

{
  "sessionId": "img_abc123xyz"
}

注意：首次运行可能需要更长时间，因为 ML 模型文件（约 10 - 50MB）需要下载和缓存。 前后对比：

extract_region

从存储在会话中的图像中提取（裁剪）一个矩形区域。将裁剪后的图像作为文件或 Base64 有效负载返回。 参数：

• sessionId（字符串，必需）：create_session 返回的会话 ID。
• x（数字，必需）：裁剪区域左上角的 X 坐标。
• y（数字，必需）：裁剪区域左上角的 Y 坐标。
• width（数字，必需）：裁剪区域的宽度。
• height（数字，必需）：裁剪区域的高度。
• output_path（字符串，可选）：保存裁剪后图像的绝对路径。如果未提供，则返回 Base64 有效负载。 返回值（无 output_path）：

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/png"
}

返回值（有 output_path）：

{
  "success": true,
  "path": "/path/to/cropped.png"
}

示例：

{
  "sessionId": "img_abc123xyz",
  "x": 100,
  "y": 50,
  "width": 200,
  "height": 150,
  "output_path": "/path/to/cropped.png"
}

错误响应：

• 越界：区域 (100, 50, 200x150) 超出图像边界 (150x100)
• 无效坐标：无效坐标：x 和 y 必须是非负值。
• 无效尺寸：无效尺寸：宽度和高度必须是正值。

compress_image

使用指定的格式和质量压缩图像。支持 JPEG、PNG 和 WebP 格式。将压缩后的图像作为文件或 Base64 有效负载返回。 参数：

• sessionId（字符串，必需）：create_session 返回的会话 ID。
• format（字符串，可选）：输出格式：'jpeg'、'png' 或 'webp'。如果未指定，则保持原始格式。
• quality（数字，可选，默认值：80）：压缩质量（1 - 100）。值越高，质量越好，但文件大小越大。
• output_path（字符串，可选）：保存压缩后图像的绝对路径。如果未提供，则返回 Base64 有效负载。 返回值（无 output_path）：

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/jpeg",
  "format": "jpeg",
  "originalSize": 245632,
  "compressedSize": 98234,
  "compressionRatio": "60.01%"
}

返回值（有 output_path）：

{
  "success": true,
  "path": "/path/to/compressed.jpg",
  "format": "jpeg",
  "originalSize": 245632,
  "compressedSize": 98234,
  "compressionRatio": "60.01%"
}

示例：

{
  "sessionId": "img_abc123xyz",
  "format": "webp",
  "quality": 75,
  "output_path": "/path/to/output.webp"
}

注意：对于 PNG 格式，质量参数将转换为压缩级别（质量 100 → 级别 0，质量 0 → 级别 9）。

💻 使用示例

示例 1：分析图像

在 Cursor/Claude Code 中：

读取 ./screenshot.png 处的截图，使用它创建一个会话，并告诉我它的尺寸。

示例 2：从 UI 中提取颜色

在 Cursor/Claude Code 中：

我有一张 UI 截图。使用它创建一个会话，并提取这些坐标处的颜色：(100, 50)、(200, 150)、(300, 200)。

示例 3：获取图像元数据

在 Cursor/Claude Code 中：

将 ./logo.png 加载到一个会话中，并获取它的大小和格式。

示例 4：去除图像背景

在 Cursor/Claude Code 中：

使用 ./product-photo.jpg 创建一个会话，并去除背景。将结果保存到 ./product-transparent.png。

示例 5：压缩并转换图像格式

在 Cursor/Claude Code 中：

将 ./large-image.png 加载到一个会话中，并将其压缩为 WebP 格式，质量为 75%。保存到 ./optimized.webp。

命令行使用

直接运行服务器：

# 使用 stdio 传输（默认）
sharp-mcp

# 使用 HTTP 传输
sharp-mcp --transport http --port 5000

CLI 选项：

• --transport <stdio|http>：传输类型（默认：stdio）
• --port <number>：HTTP 传输的端口（默认：5000）

🔧 技术细节

开发

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

# 运行测试
npm test

# 构建
npm run build

# 类型检查
npm run typecheck

# 代码检查
npm run lint

架构

该项目采用模块化架构：

• services/：会话存储和图像服务
  • session-store.ts：内存会话管理
  • image-processor.ts：基于 Sharp 的图像分析
• tools/：MCP 工具实现
  • create-session.ts：从 Base64 创建会话
  • create-session-by-path.ts：从文件路径创建会话
  • list-session.ts：会话列表
  • get-image-size.ts：图像尺寸提取（get_dimensions）
  • pick-color.ts：颜色提取
  • remove-background.ts：基于 ML 的背景去除
  • extract-region.ts：图像裁剪
  • compress-image.ts：图像压缩
• utils/：共享实用工具
  • validation.ts：会话 ID 验证
• server.ts：主 MCP 服务器设置和配置

支持的图像格式

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• TIFF (.tiff)
• AVIF (.avif)

📄 许可证

本项目采用 MIT 许可证。

贡献

欢迎贡献代码！请随时提交拉取请求。

作者

choesumin