金大哥 - sharp-mcp MCP 详情

article

README

🚀 Sharp MCP

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

🚀 快速开始

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

要求

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

✨ 主要特性

Image Processing Workflow

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 集成。

在 Cursor 中安装

前往：设置 -> Cursor 设置 -> MCP -> 添加新的全局 MCP 服务器

将以下配置添加到 ~/.cursor/mcp.json 文件中：

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

在 Claude Code 中安装

运行以下命令：

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

在 VS Code 中安装

将以下内容添加到 VS Code 的 MCP 配置文件中。更多信息请参阅 VS Code MCP 文档。

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

在 Windsurf 中安装

将以下内容添加到 Windsurf 的 MCP 配置文件中：

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

在 Claude Desktop 中安装

打开 Claude Desktop 开发者设置并编辑 claude_desktop_config.json 文件：

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

在 OpenAI Codex 中安装

将以下内容添加到 codex.toml 或 ~/.codex/config.toml 文件中：

[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）需要下载和缓存。 前后对比： | 处理前 | 处理后 | |--------|-------| | Before | After |

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

架构

Architecture Diagram 该项目采用模块化架构：

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

sharp-mcp

README

🚀 Sharp MCP

🚀 快速开始

要求

✨ 主要特性

📦 安装指南

NPM

Smithery

📚 详细文档

MCP 客户端集成

可用工具

create_session

create_session_by_path

list_session

get_dimensions

pick_color

remove_background

extract_region

compress_image

💻 使用示例

示例 1：分析图像

示例 2：从 UI 中提取颜色

示例 3：获取图像元数据

示例 4：去除图像背景

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

命令行使用

🔧 技术细节

开发

架构

支持的图像格式

📄 许可证

贡献

作者

运行方式说明

托管运行

本地运行 / 其它方式