article

README

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服务器实现

核心算法

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

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

注意事项

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

许可证

本项目采用开源许可证，具体请查看 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 |

🤝 贡献指南

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

如何贡献

Fork 这个仓库
创建你的特性分支 (git checkout -b feature/AmazingFeature)
提交你的更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开一个 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！