Image Process MCP Server

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

功能特性

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

支持的传输协议

该MCP支持Streamable HTTP协议。

安装

$3

``bash


直接运行，无需安装

npx image-process-mcp

或全局安装后运行

npm install -g image-process-mcp
image-process-mcp
`

$3

#### 前提条件

- Node.js 18+
- npm 或 yarn

#### 安装步骤

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

`bash
npm install
`

#### 构建项目

`bash
npm run build
`

使用方法

$3

#### 使用 stdio 传输（本地使用）

`bash


开发模式（自动重载）

npm run dev

运行编译后的版本

npm start

或直接运行

node dist/index.js
`

#### 使用 Streamable HTTP 传输（远程访问）

`bash
TRANSPORT=http npm start
`

默认端口为 3000，可通过环境变量修改：

`bash
PORT=8000 TRANSPORT=http npm start
`

$3

在 Claude Code 的配置文件中添加以下配置：

`json
{
"mcpServers": {
"image-process": {
"command": "npx",
"args": ["-y", "image-process-mcp@latest"]
}
}
}
`

或使用标准配置（可能不是最新版本）：

`json
{
"mcpServers": {
"image-process": {
"command": "npx",
"args": ["image-process-mcp"],
"transport": "stdio"
}
}
}
`

或使用本地安装：

`json
{
"mcpServers": {
"image-process": {
"command": "node",
"args": ["/path/to/image-process-mcp/dist/index.js"],
"transport": "stdio"
}
}
}
`

或使用 Streamable HTTP：

`json
{
"mcpServers": {
"image-process": {
"url": "http://localhost:3000",
"transport": "streamable_http"
}
}
}
`

$3

#### Claude Code
使用 Claude Code CLI 添加图像处理 MCP 服务器（指南）：
`bash
claude mcp add image-process npx image-process-mcp@latest
`

#### Codex
按照 MCP 配置指南 使用上述标准配置。您也可以使用 Codex CLI 安装图像处理 MCP 服务器：
`bash
codex mcp add image-process -- npx image-process-mcp@latest
`

#### Gemini CLI
使用 Gemini CLI 安装图像处理 MCP 服务器：
`bash


项目范围安装


gemini mcp add image-process npx image-process-mcp@latest
`

工具说明

$3

从图像 URL 中裁剪图像，返回裁剪后的图像数据 URL。如果提供了 output_path，则会将图片保存到本地。

参数：
- img_url：目标图像的 URL
- box：裁剪框坐标（千分之一比例），格式：[x1, y1, x2, y2]，每个值在 0-1000 之间
- output_path：本地保存路径（可选，如 "output.jpg"）

示例：
`json
{
"img_url": "https://example.com/image.jpg",
"box": [100, 100, 500, 500]
}
`

$3

在图像上绘制一个或多个矩形。如果提供了 output_path，则会将图片保存到本地。

参数：
- img_url：目标图像的 URL
- boxes：矩形坐标列表（千分之一比例），格式：[[x1, y1, x2, y2], ...]，每个坐标在 0-1000 之间
- color：轮廓颜色（颜色名称或十六进制），默认："red"
- thickness：轮廓厚度（参考像素值，≥1），默认：3。实际厚度会根据图像尺寸自动缩放。
- output_path：本地保存路径（可选，如 "output.jpg"）

示例：
`json
{
"img_url": "https://example.com/image.jpg",
"boxes": [[100, 100, 300, 300], [200, 200, 400, 400]],
"color": "blue",
"thickness": 2
}
`

$3

在图像上绘制一个点（实心圆）。如果提供了 output_path，则会将图片保存到本地。

参数：
- img_url：目标图像的 URL
- point：点坐标（千分之一比例），格式：[x, y]，每个值在 0-1000 之间
- color：填充颜色（颜色名称或十六进制），默认："red"
- radius：圆半径（参考像素值，≥1），默认：4。实际半径会根据图像尺寸自动缩放。
- output_path：本地保存路径（可选，如 "output.jpg"）

示例：
`json
{
"img_url": "https://example.com/image.jpg",
"point": [500, 500],
"color": "green",
"radius": 6
}
`

$3

从给定的 URL 打开一张图片，并将其作为图像数据 URL 返回。如果提供了 output_path，则会将图片保存到本地。

参数：
- url：直接图像 URL（http/https）
- output_path：本地保存路径（可选，如 "output.jpg"）

示例：
`json
{
"url": "https://example.com/image.jpg"
}
`

$3

获取图像及其 URL 以备将来参考。裁剪为可选操作。如果提供了 output_path，则会将图片保存到本地。

参数：
- img_url：目标图像的 URL
- crop_box：裁剪框坐标（千分之一比例，可选），格式：[x1, y1, x2, y2]，每个值在 0-1000 之间
- ref_name：引用图像的名称（可选）
- output_path：本地保存路径（可选，如 "output.jpg"）

示例：
`json
{
"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无效等）
- 坐标参数无效
- 图像处理错误
- 颜色格式错误

开发

$3

`
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设置
`

$3

`bash


安装依赖

npm install

开发模式（自动重载）

npm run dev

构建项目

npm run build

运行编译后的版本

npm start

清理构建文件

npm run clean
`

$3

确保遵循以下最佳实践：

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

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request。