图像处理 MCP 服务器
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"image-process": {
"args": [
"-y",
"image-process-mcp@latest"
],
"command": "npx"
}
}
}可用工具 （5 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
crop 3 个参数 需填 2 项
Crop an image from an image URL using the provided crop box and return the cropped image URL. This tool downloads an image from the provided URL, crops it according to the specified box coordinates (in thousandths of the image dimensions), and returns a data URL of the cropped image. Args: - img_url (string): The image URL of the target image - box (number[]): Crop box coordinates in thousandths [x1, y1, x2, y2] Returns: Data URL of the cropped image (format: data:image/jpeg;base64,...) Examples: - Use when: You need to extract a specific region from an image - Use when: You want to focus on a particular object in an image - Don't use when: You need to draw on the image (use draw_boxes or draw_point instead) Error Handling: - Returns error if image cannot be downloaded (invalid URL, network issues) - Returns error if crop box coordinates are invalid - Returns error if crop box extends beyond image boundaries
必填参数：img_url、box
draw_boxes 5 个参数 需填 2 项
Draw a rectangle or multiple rectangles on the image. This tool downloads an image from the provided URL, draws one or more rectangles at the specified coordinates (in thousandths of the image dimensions), and returns a data URL of the annotated image. Args: - img_url (string): The image URL of the target image - boxes (number[][]): Rectangle coordinates in thousandths [[x1, y1, x2, y2], ...] - color (string): Outline color name or hex (default: "red") - thickness (number): Outline thickness in pixels (default: 3) Returns: Data URL of the image with drawn boxes (format: data:image/jpeg;base64,...) Examples: - Use when: You need to highlight specific regions in an image - Use when: You want to draw bounding boxes around objects - Don't use when: You need to crop the image (use crop instead) Error Handling: - Returns error if image cannot be downloaded - Returns error if box coordinates are invalid - Returns error if color format is unrecognized
必填参数：img_url、boxes
open_img_url 2 个参数 需填 1 项
Open an image from a given URL and return it as an Image. This tool downloads an image from the provided URL and returns it as a data URL. No modifications are made to the image. Args: - url (string): Direct image URL (http/https) Returns: Data URL of the original image (format: data:image/jpeg;base64,...) Examples: - Use when: You need to load an image for reference or further processing - Use when: You want to display an image without modifications - Don't use when: You need to modify the image (use crop, draw_boxes, or draw_point instead) Error Handling: - Returns error if image cannot be downloaded - Returns error if URL is not accessible
必填参数：url
draw_point 5 个参数 需填 2 项
Draw a point (filled circle) on the image. This tool downloads an image from the provided URL, draws a filled circle at the specified coordinates (in thousandths of the image dimensions), and returns a data URL of the annotated image. Args: - img_url (string): The image URL of the target image - point (number[]): Point coordinates in thousandths [x, y] - color (string): Fill color name or hex (default: "red") - radius (number): Circle radius in pixels (default: 4) Returns: Data URL of the image with drawn point (format: data:image/jpeg;base64,...) Examples: - Use when: You need to mark a specific location in an image - Use when: You want to highlight a point of interest - Don't use when: You need to draw rectangles (use draw_boxes instead) Error Handling: - Returns error if image cannot be downloaded - Returns error if point coordinates are invalid - Returns error if color format is unrecognized
必填参数：img_url、point
image_reference 4 个参数 需填 1 项
Get the image and its URL for future reference. Cropping is optional. This tool downloads an image from the provided URL, optionally crops it, and returns a data URL. The reference name parameter is stored for future use in more advanced implementations. Args: - img_url (string): The URL of the target image - crop_box (number[]): Crop box coordinates in thousandths [x1, y1, x2, y2] (optional) - ref_name (string): The name for the referenced image (optional) Returns: Data URL of the (optionally cropped) image (format: data:image/jpeg;base64,...) Examples: - Use when: You need to save an image for later use - Use when: You want to store a cropped version of an image - Don't use when: You need immediate image manipulation (use other tools instead) Error Handling: - Returns error if image cannot be downloaded - Returns error if crop box coordinates are invalid
必填参数：img_url
服务介绍
Image Process MCP Server
图像处理 MCP 服务器，专注于为用户提供便捷、高效的图像处理（如裁剪、获取URL、画框等）能力，能够无缝集成到各类图像处理应用场景，满足不同用户的多样化需求。
功能特性
- 裁剪图像：使用提供的裁剪框从图像 URL 中裁剪图像
- 绘制矩形框：在图像上绘制一个或多个矩形
- 绘制点：在图像上绘制一个点（实心圆）
- 打开图像URL：从给定的 URL 打开一张图片
- 图像引用：获取图片及其 URL 以备将来参考，裁剪为可选操作
- 本地文件保存：所有工具支持通过
output_path参数将处理后的图像直接保存到本地文件系统
支持的传输协议
该MCP支持Streamable HTTP协议。
安装
通过 NPX 直接运行（推荐）
# 直接运行，无需安装
npx image-process-mcp
# 或全局安装后运行
npm install -g image-process-mcp
image-process-mcp
本地开发安装
前提条件
- Node.js 18+
- npm 或 yarn
安装步骤
- 克隆或下载本仓库
- 安装依赖：
npm install
构建项目
npm run build
使用方法
作为MCP服务器运行
使用 stdio 传输（本地使用）
# 开发模式（自动重载）
npm run dev
# 运行编译后的版本
npm start
# 或直接运行
node dist/index.js
使用 Streamable HTTP 传输（远程访问）
TRANSPORT=http npm start
默认端口为 3000，可通过环境变量修改：
PORT=8000 TRANSPORT=http npm start
集成到 Claude Code
在 Claude Code 的配置文件中添加以下配置：
{
"mcpServers": {
"image-process": {
"command": "npx",
"args": ["-y", "image-process-mcp@latest"]
}
}
}
或使用标准配置（可能不是最新版本）：
{
"mcpServers": {
"image-process": {
"command": "npx",
"args": ["image-process-mcp"],
"transport": "stdio"
}
}
}
或使用本地安装：
{
"mcpServers": {
"image-process": {
"command": "node",
"args": ["/path/to/image-process-mcp/dist/index.js"],
"transport": "stdio"
}
}
}
或使用 Streamable HTTP：
{
"mcpServers": {
"image-process": {
"url": "http://localhost:3000",
"transport": "streamable_http"
}
}
}
通过 CLI 工具快速添加
Claude Code
使用 Claude Code CLI 添加图像处理 MCP 服务器（指南）：
claude mcp add image-process npx image-process-mcp@latest
Codex
按照 MCP 配置指南 使用上述标准配置。您也可以使用 Codex CLI 安装图像处理 MCP 服务器：
codex mcp add image-process -- npx image-process-mcp@latest
Gemini CLI
使用 Gemini CLI 安装图像处理 MCP 服务器：
# 项目范围安装
gemini mcp add image-process npx image-process-mcp@latest
工具说明
1. crop
从图像 URL 中裁剪图像，返回裁剪后的图像数据 URL。如果提供了 output_path，则会将图片保存到本地。
参数：
img_url：目标图像的 URLbox：裁剪框坐标（千分之一比例），格式：[x1, y1, x2, y2]，每个值在 0-1000 之间output_path：本地保存路径（可选，如 "output.jpg"）
示例：
{
"img_url": "https://example.com/image.jpg",
"box": [100, 100, 500, 500]
}
2. draw_boxes
在图像上绘制一个或多个矩形。如果提供了 output_path，则会将图片保存到本地。
参数：
img_url：目标图像的 URLboxes：矩形坐标列表（千分之一比例），格式：[[x1, y1, x2, y2], ...]，每个坐标在 0-1000 之间color：轮廓颜色（颜色名称或十六进制），默认："red"thickness：轮廓厚度（参考像素值，≥1），默认：3。实际厚度会根据图像尺寸自动缩放。output_path：本地保存路径（可选，如 "output.jpg"）
示例：
{
"img_url": "https://example.com/image.jpg",
"boxes": [[100, 100, 300, 300], [200, 200, 400, 400]],
"color": "blue",
"thickness": 2
}
3. draw_point
在图像上绘制一个点（实心圆）。如果提供了 output_path，则会将图片保存到本地。
参数：
img_url：目标图像的 URLpoint：点坐标（千分之一比例），格式：[x, y]，每个值在 0-1000 之间color：填充颜色（颜色名称或十六进制），默认："red"radius：圆半径（参考像素值，≥1），默认：4。实际半径会根据图像尺寸自动缩放。output_path：本地保存路径（可选，如 "output.jpg"）
示例：
{
"img_url": "https://example.com/image.jpg",
"point": [500, 500],
"color": "green",
"radius": 6
}
4. open_img_url
从给定的 URL 打开一张图片，并将其作为图像数据 URL 返回。如果提供了 output_path，则会将图片保存到本地。
参数：
url：直接图像 URL（http/https）output_path：本地保存路径（可选，如 "output.jpg"）
示例：
{
"url": "https://example.com/image.jpg"
}
5. image_reference
获取图像及其 URL 以备将来参考。裁剪为可选操作。如果提供了 output_path，则会将图片保存到本地。
参数：
img_url：目标图像的 URLcrop_box：裁剪框坐标（千分之一比例，可选），格式：[x1, y1, x2, y2]，每个值在 0-1000 之间ref_name：引用图像的名称（可选）output_path：本地保存路径（可选，如 "output.jpg"）
示例：
{
"img_url": "https://example.com/image.jpg",
"crop_box": [200, 200, 600, 600],
"ref_name": "my_reference"
}
坐标系统说明
所有坐标参数都使用千分之一比例系统：
- 坐标值范围：0-1000
- 实际像素坐标 = round(坐标值 × 图像尺寸 / 1000)
- 例如：在 1000×800 的图像上，坐标 [500, 400] 对应像素坐标 (500×1000/1000, 400×800/1000) = (500, 320)
标注尺寸缩放：
为了在不同尺寸的图片上保持标注（如线宽、圆半径）的视觉比例，服务器会根据图片尺寸自动缩放 thickness 和 radius。
- 缩放因子 = sqrt(宽度 × 高度) / 1000
- 实际像素值 = max(1, round(输入值 × 缩放因子))
这种设计使得坐标系统与图像尺寸无关，便于在不同尺寸的图像上使用相同的坐标。
错误处理
服务器提供清晰的错误消息，包括：
- 图像下载失败（网络问题、URL无效等）
- 坐标参数无效
- 图像处理错误
- 颜色格式错误
开发
项目结构
image-process-mcp/
├── src/index.ts # TypeScript MCP服务器主文件
├── dist/index.js # 编译后的JavaScript文件
├── package.json # Node.js依赖和配置
├── tsconfig.json # TypeScript配置
├── README.md # 本文档
├── node_modules/ # 依赖包
└── .claude/ # Claude Code设置
构建和测试
# 安装依赖
npm install
# 开发模式（自动重载）
npm run dev
# 构建项目
npm run build
# 运行编译后的版本
npm start
# 清理构建文件
npm run clean
TypeScript代码质量检查
确保遵循以下最佳实践：
- 工具注册：使用
server.registerTool()而不是旧的API - 输入验证：使用Zod进行运行时输入验证
- 类型安全：完整的TypeScript类型定义
- 异步操作：所有网络请求使用 async/await
- 错误处理：统一的错误处理和清晰的错误消息
- 文档完整：所有工具都有完整的描述和示例
- 最佳实践：遵循MCP TypeScript SDK指南
许可证
本项目采用 MIT 许可证。
贡献
欢迎提交 Issue 和 Pull Request。
