Image Processing Toolkits

图片处理 MCP 服务器

这是一个功能强大的图片处理MCP (Model Context Protocol) 服务器，提供了丰富的图片处理功能，包括裁剪、旋转、调整大小、对比度调整等。

功能特性

🎨 基础图片处理

• 裁剪图片 - 精确裁剪到指定区域
• 旋转图片 - 任意角度旋转，支持画布扩展
• 调整大小 - 智能缩放，可保持宽高比
• 翻转图片 - 水平或垂直翻转

🌈 图片增强

• 对比度调整 - 增强或减弱图片对比度
• 亮度调整 - 调节图片明暗程度
• 饱和度调整 - 控制色彩饱和度，支持灰度转换

🎭 滤镜效果

• 模糊效果 (BLUR)
• 细节增强 (DETAIL)
• 边缘增强 (EDGE_ENHANCE, EDGE_ENHANCE_MORE)
• 浮雕效果 (EMBOSS)
• 边缘检测 (FIND_EDGES)
• 锐化 (SHARPEN)
• 平滑 (SMOOTH, SMOOTH_MORE)

🔧 实用工具

• 格式转换 - 支持 JPEG, PNG, BMP, TIFF, WEBP
• 缩略图生成 - 快速生成指定尺寸缩略图
• 水印添加 - 文字水印，支持多种位置和透明度
• 图片信息获取 - 详细的元数据和EXIF信息

⚡ 性能优化

• 智能缓存 - 自动缓存常用图片，提升处理速度
• 内存管理 - 监控内存使用，自动清理过期缓存
• 并发处理 - 支持多线程并发处理
• 错误处理 - 完善的错误处理和恢复机制

安装和配置

1. 安装依赖

在使用图片处理服务器之前，需要安装以下依赖包：

pip install Pillow opencv-python numpy psutil mcp[cli]

或者使用项目的配置文件：

pip install -r requirements.txt

注意: 必须安装 mcp[cli] 而不是单独的 mcp，这样才能包含所需的 CLI 工具和依赖（如 typer）。

2. MCP Server 配置

要在支持MCP的应用程序中使用此图像处理服务器，请将以下配置添加到您的MCP配置文件中：

Claude Desktop 配置

在 %APPDATA%\Claude\claude_desktop_config.json (Windows) 或 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 中添加：

{
    "mcpServers": {
        "image_processing_toolkits": {
            "command": "python",
            "args": [
                "e:/MyProjects/TOBench/server_tools/local_servers/image-processing-toolkits/src/server.py"
            ],
            "cwd": "e:/MyProjects/TOBench/server_tools/local_servers/image-processing-toolkits"
        }
    }
}

使用 uv 运行器的配置

如果您使用 uv 作为 Python 包管理器：

{
    "mcpServers": {
        "image_processing_toolkits": {
            "command": "uv",
            "args": [
                "--directory",
                "e:/MyProjects/TOBench/server_tools/local_servers/image-processing-toolkits",
                "run",
                "python",
                "src/server.py"
            ]
        }
    }
}

通用配置模板

请将路径替换为您的实际安装路径：

{
    "mcpServers": {
        "image_processing_toolkits": {
            "command": "python",
            "args": [
                "/path/to/image-processing-toolkits/src/server.py"
            ],
            "cwd": "/path/to/image-processing-toolkits"
        }
    }
}

FastMCP 特性

本服务器使用 FastMCP 框架构建，提供以下优势：

• 简化的工具定义: 使用 @mcp.tool() 装饰器直接定义工具
• 自动类型推断: 从函数签名自动生成工具模式
• 更少的样板代码: 无需手动定义复杂的工具列表和处理器
• 更好的开发体验: 专注于业务逻辑而非协议细节
• 自动文档生成: 从函数docstring自动生成工具描述

3. 启动服务器

直接启动

python src/server.py

使用 uv 启动

uv run python src/server.py

4. 验证安装

启动服务器后，您应该看到以下消息：

Image Processing MCP Server starting...

如果配置正确，MCP客户端将能够发现并使用所有12个图像处理工具。

可用工具

1. crop-image - 裁剪图片

{
  "file_path": "path/to/image.jpg",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 150,
  "output_path": "path/to/cropped.jpg"  // 可选
}

2. rotate-image - 旋转图片

{
  "file_path": "path/to/image.jpg",
  "angle": 45,
  "expand": true,  // 是否扩展画布
  "output_path": "path/to/rotated.jpg"  // 可选
}

3. resize-image - 调整大小

{
  "file_path": "path/to/image.jpg",
  "width": 800,
  "height": 600,
  "maintain_aspect": true,  // 保持宽高比
  "resample": "LANCZOS",    // LANCZOS, BILINEAR, BICUBIC, NEAREST
  "output_path": "path/to/resized.jpg"  // 可选
}

4. adjust-contrast - 调整对比度

{
  "file_path": "path/to/image.jpg",
  "factor": 1.5,  // >1增强, 1增亮, 1增强, <1减弱, 0灰度, 1.0原始
  "output_path": "path/to/saturated.jpg"  // 可选
}

7. apply-filter - 应用滤镜

{
  "file_path": "path/to/image.jpg",
  "filter_type": "BLUR",  // 见上方滤镜列表
  "output_path": "path/to/filtered.jpg"  // 可选
}

8. flip-image - 翻转图片

{
  "file_path": "path/to/image.jpg",
  "direction": "horizontal",  // horizontal, vertical
  "output_path": "path/to/flipped.jpg"  // 可选
}

9. convert-format - 转换格式

{
  "file_path": "path/to/image.png",
  "format": "JPEG",
  "quality": 95,  // JPEG质量 1-100
  "output_path": "path/to/converted.jpg"  // 可选
}

10. get-image-info - 获取图片信息

{
  "file_path": "path/to/image.jpg"
}

11. create-thumbnail - 创建缩略图

{
  "file_path": "path/to/image.jpg",
  "size": 128,  // 最大尺寸
  "output_path": "path/to/thumbnail.jpg"  // 可选
}

12. add-watermark - 添加水印

{
  "file_path": "path/to/image.jpg",
  "watermark_text": "版权所有",
  "position": "bottom-right",  // top-left, top-right, bottom-left, bottom-right, center
  "opacity": 0.7,  // 透明度 0.0-1.0
  "font_size": 36,
  "output_path": "path/to/watermarked.jpg"  // 可选
}

使用示例

启动服务器

python src/server.py

使用 uv 启动

uv run python src/server.py

在MCP客户端中使用

配置完成后，您可以在支持MCP的应用程序（如Claude Desktop）中直接使用图像处理功能：

1. 裁剪图片: 使用 crop-image 工具精确裁剪图片区域
2. 调整大小: 使用 resize-image 工具智能缩放图片
3. 应用滤镜: 使用 apply-filter 工具为图片添加各种视觉效果
4. 格式转换: 使用 convert-format 工具在不同图片格式间转换
5. 添加水印: 使用 add-watermark 工具为图片添加文字水印

所有工具都支持自动生成输出文件名，或者您可以指定自定义的输出路径。

技术特性

缓存机制

• 自动缓存最近使用的图片
• 内存使用率监控
• 定期清理过期缓存
• 支持手动清理缓存

错误处理

• 完善的异常处理机制
• 详细的错误信息反馈
• 自动恢复和重试机制

性能优化

• 多线程并发处理
• 智能内存管理
• 高效的图片处理算法
• 支持大文件处理

文件结构

image-processing-toolkits/
├── src/
│   └── server.py          # 主MCP服务器文件
├── LICENSE                # 许可证文件
├── pyproject.toml         # 项目配置和依赖
├── requirements.txt       # Python依赖列表
└── README.md             # 项目文档（本文档）

注意事项

1. 依赖安装: 确保所有依赖包都已正确安装
2. 文件路径: 使用绝对路径或相对于当前工作目录的路径
3. 图片格式: 支持常见的图片格式 (JPEG, PNG, BMP, TIFF, WEBP)
4. 内存使用: 处理大图片时注意内存使用情况
5. 输出路径: 如果不指定输出路径，会自动生成带后缀的文件名

故障排除

常见问题

1. PIL导入失败

   pip install Pillow --upgrade

1. OpenCV导入失败

   pip install opencv-python --upgrade

1. 内存不足

- 减少缓存大小 - 处理较小的图片 - 手动清理缓存

1. 字体加载失败

- 水印功能会自动回退到默认字体 - 可以手动指定字体路径

扩展功能

这个图片处理服务器采用模块化设计，可以轻松添加新的功能：

1. 新增滤镜: 在 apply_filter 函数中添加新的滤镜类型
2. 自定义处理: 创建新的处理函数并注册为工具
3. 格式支持: 扩展支持的图片格式
4. 批量处理: 添加批量处理功能

许可证

本项目采用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！