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