Image Process MCP Server

图像处理 MCP 服务器，专注于为用户提供便捷、高效的图像处理（如裁剪、获取URL、画框等）能力，能够无缝集成到各类图像处理应用场景，满足不同用户的多样化需求。

功能特性

• 裁剪图像：使用提供的裁剪框从图像 URL 中裁剪图像
• 绘制矩形框：在图像上绘制一个或多个矩形
• 绘制点：在图像上绘制一个点（实心圆）
• 打开图像URL：从给定的 URL 打开一张图片
• 图像引用：获取图片及其 URL 以备将来参考，裁剪为可选操作
• 本地文件保存：所有工具支持通过 output_path 参数将处理后的图像直接保存到本地文件系统
• 智能预览优化：针对 IDE (如 Cursor/Trae) 和大模型进行了优化。返回的 Base64 预览图会自动缩放至 1024px 以内并进行压缩，在保证模型理解能力的同时最大限度减少 Token 消耗，而保存到本地的文件则保持原始质量。

支持的传输协议

该MCP支持Streamable HTTP协议。

安装

通过 NPX 直接运行（推荐）

# 直接运行，无需安装
npx image-process-mcp

# 或全局安装后运行
npm install -g image-process-mcp
image-process-mcp

本地开发安装

前提条件

• Node.js 18+
• npm 或 yarn

安装步骤

1. 克隆或下载本仓库
2. 安装依赖：

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：目标图像的 URL
• box：裁剪框坐标（千分之一比例），格式：[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：目标图像的 URL
• boxes：矩形坐标列表（千分之一比例），格式：[[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：目标图像的 URL
• point：点坐标（千分之一比例），格式：[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：目标图像的 URL
• crop_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代码质量检查

确保遵循以下最佳实践：

1. 工具注册：使用 server.registerTool() 而不是旧的API
2. 输入验证：使用Zod进行运行时输入验证
3. 类型安全：完整的TypeScript类型定义
4. 异步操作：所有网络请求使用 async/await
5. 错误处理：统一的错误处理和清晰的错误消息
6. 文档完整：所有工具都有完整的描述和示例
7. 最佳实践：遵循MCP TypeScript SDK指南

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request。