Undoom Sketch MCP

一个基于 MCP (Model Context Protocol) 的图片素描化服务器，可以将普通图片转换为多种风格的素描效果。支持单张图片转换、批量处理，以及多种自定义参数调节。

🌟 在线体验

项目已发布到 PyPI，可以直接使用：

• PyPI: undoom-sketch-mcp
• GitHub: undoom-sketch-mcp

功能特性

• 🎨 多种素描风格：支持经典、详细、柔和三种不同的素描风格
• 📁 批量处理：支持批量转换文件夹中的所有图片
• 🖼️ 多格式支持：支持 JPG、PNG、BMP、GIF、TIFF、WEBP 等常见图片格式
• 🌏 中文路径支持：完美支持中文文件名和路径
• ⚙️ 参数可调：可自定义模糊程度和对比度参数
• 📊 图片信息查看：提供图片基本信息和推荐参数

安装要求

• Python >= 3.13
• 依赖包：
  • mcp[cli] >= 1.12.3
  • opencv-python >= 4.8.0
  • numpy >= 1.24.0

🚀 快速开始

方法一：直接使用 uvx（推荐）

# 使用国内镜像源（推荐）
uvx --index-url https://pypi.tuna.tsinghua.edu.cn/simple undoom-sketch-mcp

# 或使用默认源
uvx undoom-sketch-mcp

方法二：通过 PyPI 安装

# 安装包
pip install undoom-sketch-mcp

# 运行服务器
python -m undoom_sketch_mcp

方法三：从源码安装

# 克隆项目
git clone https://github.com/kk520879/undoom-sketch-mcp.git
cd undoom-sketch-mcp

# 使用 uv 安装（推荐）
uv sync

# 或使用 pip
pip install -e .

📖 使用方法

作为 MCP 服务器使用

1. 配置 MCP 客户端

创建 mcp_config.json 配置文件：

{
  "mcpServers": {
    "undoom-sketch-mcp": {
      "command": "uvx",
      "args": [
        "--index-url",
        "https://pypi.tuna.tsinghua.edu.cn/simple",
        "undoom-sketch-mcp"
      ]
    }
  }
}

2. 直接运行服务器

# 启动 MCP 服务器
python -m undoom_sketch_mcp

# 或使用 uvx
uvx undoom-sketch-mcp

🛠️ 可用工具

1. convert_image_to_sketch - 单张图片转换

MCP 调用示例：

{
  "tool": "convert_image_to_sketch",
  "arguments": {
    "image_path": "D:\\photos\\portrait.jpg",
    "style": "classic",
    "blur_size": 21,
    "contrast": 256.0
  }
}

Python 直接调用：

from undoom_sketch_mcp.server import convert_image_to_sketch

result = convert_image_to_sketch(
    image_path="D:/photos/portrait.jpg",
    style="classic",
    blur_size=21,
    contrast=256.0
)
print(result)

2. batch_convert_images - 批量图片转换

from undoom_sketch_mcp.server import batch_convert_images

result = batch_convert_images(
    folder_path="D:/photos/",
    style="detailed",
    blur_size=21,
    contrast=256.0
)
print(result)

3. get_image_info - 获取图片信息

from undoom_sketch_mcp.server import get_image_info

info = get_image_info("D:/photos/image.jpg")
print(info)

素描风格说明

• classic：经典素描风格，平衡的线条和对比度
• detailed：详细素描风格，更清晰的线条和细节
• soft：柔和素描风格，更柔和的效果，适合风景图

参数说明

• image_path：图片文件的完整路径（必需）
• blur_size：高斯模糊核大小（3-101，必须为奇数，默认21）
• contrast：对比度参数（50-500，默认256.0）
• style：素描风格（classic/detailed/soft，默认classic）

参数建议

• 大图片（>200万像素）：blur_size=31-51，contrast=200-300
• 中等图片（50万-200万像素）：blur_size=21-31，contrast=256
• 小图片（<50万像素）：blur_size=11-21，contrast=300-400

输出文件

转换后的素描图片会保存在原图片相同目录下，文件名格式为：

Sketch_{style}_{原文件名}.jpg

例如：Sketch_classic_photo.jpg

支持的图片格式

• JPG / JPEG
• PNG
• BMP
• GIF
• TIFF
• WEBP

技术实现

本项目使用以下技术：

• OpenCV：图像处理和计算机视觉
• NumPy：数值计算
• MCP (Model Context Protocol)：与AI模型的通信协议
• FastMCP：快速MCP服务器实现

核心算法

素描效果通过以下步骤实现：

1. 将彩色图片转换为灰度图
2. 创建反转的灰度图
3. 对反转图像应用高斯模糊
4. 使用颜色减淡混合模式生成素描效果
5. 根据风格进行后处理优化

注意事项

• 确保图片文件存在且可读
• 处理大图片时可能需要较长时间
• 建议在处理前备份原图片
• 支持中文路径和文件名

许可证

本项目采用开源许可证，具体请查看 LICENSE 文件。

📁 项目结构

undoom-sketch-mcp/
├── undoom_sketch_mcp/          # 主要源码目录
│   ├── __init__.py            # 包初始化文件
│   ├── __main__.py            # 命令行入口
│   └── server.py              # MCP 服务器实现
├── pyproject.toml             # 项目配置文件
├── README.md                  # 项目说明文档
├── LICENSE                    # MIT 许可证
├── MCP使用说明.txt            # 中文详细使用说明
├── mcp_config.json            # MCP 配置示例
└── simple_sketch_example.py   # 简单使用示例

🎯 实际应用示例

处理单张图片

# 经典风格素描
result = convert_image_to_sketch(
    "D:/photos/portrait.jpg",
    style="classic"
)

# 细节风格，适合风景照
result = convert_image_to_sketch(
    "D:/photos/landscape.jpg",
    style="detailed",
    blur_size=15,
    contrast=300.0
)

# 柔和风格，适合人像
result = convert_image_to_sketch(
    "D:/photos/selfie.jpg",
    style="soft",
    blur_size=25,
    contrast=200.0
)

批量处理文件夹

# 批量转换所有图片为经典风格
batch_convert_images(
    "D:/vacation_photos/",
    style="classic"
)

# 批量转换为细节风格，自定义参数
batch_convert_images(
    "D:/artwork/",
    style="detailed",
    blur_size=31,
    contrast=280.0
)

🔧 故障排除

常见问题

Q: 安装时提示找不到包？ A: 使用国内镜像源：

uvx --index-url https://pypi.tuna.tsinghua.edu.cn/simple undoom-sketch-mcp

Q: 图片处理失败？ A: 检查以下几点：

• 图片路径是否正确
• 图片格式是否支持
• 文件是否有读取权限
• 输出目录是否有写入权限

Q: 处理大图片很慢？ A: 建议：

• 增大 blur_size 参数（如 31-51）
• 降低图片分辨率
• 使用 "soft" 风格处理更快

Q: MCP 连接失败？ A: 确认：

• 配置文件格式正确
• 服务器正常启动
• 网络连接正常

📊 性能参考

图片尺寸	处理时间	推荐参数
< 1MP	1-3秒	blur_size=11-21
1-5MP	3-10秒	blur_size=21-31
5-10MP	10-30秒	blur_size=31-41
> 10MP	30秒+	blur_size=41-51

🤝 贡献指南

我们欢迎各种形式的贡献！

如何贡献

1. Fork 这个仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

报告问题

如果你发现了 bug 或有功能建议，请在 GitHub Issues 中提交。

开发环境设置

# 克隆仓库
git clone https://github.com/kk520879/undoom-sketch-mcp.git
cd undoom-sketch-mcp

# 安装开发依赖
uv sync --dev

# 运行测试
python -m pytest

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

• OpenCV - 强大的计算机视觉库
• MCP - 模型上下文协议
• FastMCP - 快速 MCP 实现

---

如果这个项目对你有帮助，请给它一个 ⭐ Star！