图像识别编辑工具

ImageSorcery MCP是一款基于计算机视觉的本地图像识别和编辑工具,为AI助手提供强大的图像处理能力,包括裁剪、旋转、背景去除、OCR等功能。

  • by sunriseapps
  • Python
  • 本地部署
  • 334 星标
  • 更新于
在 GitHub 查看 sunriseapps/imagesorcery-mcp

使用说明

🪄 ImageSorcery MCP

基于计算机视觉🪄 人工智能助手的局部图像识别和编辑工具的魔法

官方网站: imagemagicy.net

✅ 使用ImageSorcery MCP

🪄 ImageSorcery 赋予AI助手强大的图像处理能力:

  • ✅ 精确裁剪、调整大小和旋转图像
  • ✅ 删除背景
  • ✅ 在图像上绘制文本和形状
  • ✅ 添加徽标和水印
  • ✅ 使用最先进的模型检测物体
  • ✅ 使用OCR从图像中提取文本
  • ✅ 使用广泛的预训练模型进行对象检测、OCR等
  • ✅ 完成所有这些 本地,无需将图像发送到任何服务器

只需让你的AI帮助完成图像任务:

“从文件夹中复制带宠物的照片 photos 到文件夹 pets"

“在photo.jpg中找到一只猫,并将图像的高度和宽度裁剪成两半,使猫居中” 😉 提示: 使用文件的完整路径”。

“枚举此表单字段 form.jpg 随着 foduucom/web-form-ui-field-detection 建模并填充 form.md 带有所描述字段的列表” 😉 提示: 指定模型和置信度”。

😉 提示: 添加“use imagemagcy”以确保它将使用正确的工具。

您的工具将结合下面列出的多个工具来实现您的目标。

🛠️ 可用工具

工具 描述 示例提示
blur 使用OpenCV模糊图像的指定矩形或多边形区域。还可以反转提供的区域,例如模糊背景。 “在我的图像'test_image.png'中用21的模糊强度将区域从(150100)模糊到(250200),并将其另存为'output.png'”
change_color 更改图像的调色板 “将我的图像'test_image.png'转换为棕褐色,并将其另存为'output.png'”
config 查看和更新ImageSorcery MCP配置设置 “显示当前配置”或“将默认检测置信度设置为0.8”
crop 使用OpenCV的NumPy切片方法裁剪图像 “将我的图像'input.png'从坐标(10,10)裁剪到(200200),并将其另存为'cuted.png'”
detect 使用Ultralytics的模型检测图像中的对象。可以返回分割蒙版(作为PNG文件)或多边形。 “以0.4的置信阈值检测我的图像'photo.jpg'中的对象”
draw_arrows 使用OpenCV在图像上绘制箭头 “在我的图像'photo.jpg'上从(50,50)到(150100)绘制一个红色箭头”
draw_circles 使用OpenCV在图像上绘制圆圈 “在我的图像'photo.jpg'上绘制一个中心为100100、半径为50的红色圆圈”
draw_lines 使用OpenCV在图像上绘制线条 “在我的图像'photo.jpg'上从(50,50)到(150100)绘制一条红线”
draw_rectangles 使用OpenCV在图像上绘制矩形 “在我的图像'photo.jpg'上绘制一个从(50,50)到(150100)的红色矩形和一个(200150)到(300250)的填充蓝色矩形”
draw_texts 使用OpenCV在图像上绘制文本 “在位置(50,50)添加文本‘Hello World’,并在我的图像‘photo.jpg’的右下角添加‘版权2023’”
fill 用颜色和不透明度填充图像中指定的矩形、多边形或基于遮罩的区域,或使其透明。还可以反转提供的区域,例如删除背景。 “在我的图像'test_image.png'中用半透明红色填充(150100)到(250200)的区域”
find 根据文本描述在图像中查找对象。可以返回分割蒙版(作为PNG文件)或多边形。 “在我的图片'photo.jpg'中找到所有狗,置信阈值为0.4”
get_metainfo 获取有关图像文件的元数据信息 “获取有关我的图像'photo.jpg'的元数据信息”
ocr 使用EasyOCR对图像执行光学字符识别(OCR) “使用英语OCR从我的图像'document.jpg'中提取文本”
overlay 将一个图像叠加在另一个图像之上,处理透明度 “将'logo.png'叠加在'background.jpg'之上的位置(10,10)”
resize 使用OpenCV调整图像大小 “将我的图像‘photo.jpg’调整为800x600像素,并将其另存为‘resized_photo.jpg’”
rotate 使用imutils.rotate_bound函数旋转图像 “将我的图像'photo.jpg'旋转45度并将其另存为'rotated_photo.jpg”

😉 提示: 每个工具的详细信息和使用说明可以在工具的 /src/imagesorcery_mcp/tools/README.md.

📚 可用资源

资源URI 描述 示例提示
models://list 列出模型目录中的所有可用模型 “ImageSorcery中有哪些可用模型?”

😉 提示: 每个资源的详细信息和使用说明可以在资源的 /src/imagesorcery_mcp/resources/README.md.

💬 可用提示

提示名称 描述 用法示例
remove-background 使用对象检测和遮罩工具指导AI完成全面的背景移除工作流程 “使用移除背景提示从我的照片'portrait.jpg'中移除背景,只保留人物”

😉 提示: 每个提示的详细信息和使用说明可以在提示中找到 /src/imagesorcery_mcp/prompts/README.md.

🚀 入门指南

需求

  • Python 3.10 或更高
  • pipx (推荐)-便于安装和虚拟环境管理
  • ffmpeg, libsm6, libxext6, libgl1-mesa-glx -OpenCV所需的系统库
  • Claude.app, Cline,或另一个MCP客户端
Virtual environments (e.g. Docker)

这些依赖关系通常包含在OpenCV安装中,不需要单独安装。但它们可能在Docker等虚拟环境中缺失。

对于Ubuntu/Debian系统:

sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

对于Docker容器: 将此行添加到您的Dockerfile中:

RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

安装

For Cline just copy-paste LLM-INSTALL.md
1.  Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
2.  Run command `pipx install imagesorcery-mcp`
3.  Run command `imagesorcery-mcp --post-install`
4.  Create or modify *MCP-configuration file*.
5.  Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
    `"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}`
6.  Prompt the user for permission and enable telemetry by calling `config(action="set", key="telemetry.enabled", value=True, persist=True)`.
7.  Attempt completion, indicating that the installation and configuration are complete.

方法1:使用pipx(推荐)

pipx 是安装ImageSorcery MCP的推荐方式,因为它会自动处理虚拟环境的创建和管理,使安装过程更加简单。

0. Install pipx (if not already installed):
  1. 安装管道(如果尚未安装):
    # On macOS with Homebrew:
    brew install pipx
    
    # On Ubuntu/Debian:
    sudo apt update && sudo apt install pipx
    
    # On other systems with pip:
    pip install --user pipx
    pipx ensurepath
    
  1. 使用pipx安装ImageSorcery MCP:

    pipx install imagesorcery-mcp
    
  2. 运行安装后脚本: 这一步至关重要。它下载所需的模型并尝试安装 clip GitHub上的Python包。

    imagesorcery-mcp --post-install
    

方法2:手动虚拟环境(方案B)

If pipx doesn't work for your system, you can manually create a virtual environment

为了确保所有组件的可靠安装,尤其是 clip 软件包(通过安装后脚本安装),它是 强烈建议使用Python的内置 venv 模块而不是 uv venv.

  1. 创建并激活虚拟环境:

    python -m venv imagesorcery-mcp
    source imagesorcery-mcp/bin/activate  # For Linux/macOS
    # source imagesorcery-mcp\Scripts\activate    # For Windows
    
  2. 将软件包安装到激活的虚拟环境中: 你可以使用 pip 或 uv pip.

    pip install imagesorcery-mcp
    # OR, if you prefer using uv for installation into the venv:
    # uv pip install imagesorcery-mcp
    
  3. 运行安装后脚本: 这一步至关重要。它下载所需的模型并尝试安装 clip Python包从GitHub进入活动虚拟环境。

    imagesorcery-mcp --post-install
    

注: 使用此方法时,您需要在MCP客户端配置中提供可执行文件的完整路径(例如。, /full/path/to/venv/bin/imagesorcery-mcp).

附加说明

What does the post-installation script do? The `imagesorcery-mcp --post-install` script performs the following actions:
  • 创建一个 config.toml 配置文件 在当前目录中,允许用户自定义默认工具参数。
  • 创建一个 models 目录(通常在虚拟环境的sitepackages目录中,如果全局安装,则位于用户特定的位置)来存储预训练的模型。
  • 生成首字母 models/model_descriptions.json 文件在那里。
  • 下载默认YOLO型号(yoloe-11l-seg-pf.pt, yoloe-11s-seg-pf.pt, yoloe-11l-seg.pt, yoloe-11s-seg.pt)所要求的 detect 工具进入此 models 目录。
  • 尝试安装 clip Python包 从Ultralytics的GitHub存储库直接导入活动的Python环境。这是文本提示功能所必需的 find 工具。
  • 下载所需的CLIP模型文件 find 工具进入 models 目录。

您可以随时运行此过程以还原默认模型并尝试 clip 安装。

Important Notes for `uv` users (uv venv and uvx)
  • 使用 uv venv 创建虚拟环境: 基于测试,创建了虚拟环境 uv venv 可能不包括 pip 以一种允许 imagesorcery-mcp --post-install 自动安装的脚本 clip 来自GitHub的包(这可能会导致在执行过程中出现“No module named pip”错误 clip 安装步骤)。 如果你选择使用 uv venv:

    1. 创建并激活您的 uv venv.
    2. 安装 imagesorcery-mcp: uv pip install imagesorcery-mcp.
    3. 手动安装 clip 打包到您的活动 uv venv:
      uv pip install git+https://github.com/ultralytics/CLIP.git
      
    4. 跑 imagesorcery-mcp --post-install。这将下载模型,但可能无法安装 clip Python包。 实现更平稳的自动化 clip 通过安装后脚本进行安装,使用 python -m venv (如上述步骤1所述)是创建虚拟环境的推荐方法。
  • 使用 uvx imagesorcery-mcp --post-install: 直接使用以下命令运行安装后脚本 uvx (例如。, uvx imagesorcery-mcp --post-install)可能无法安装 clip Python包。这是因为由以下因素创建的临时环境 uvx 通常没有 pip 以脚本可以使用的方式提供。模型将被下载,但 clip 此命令不会安装程序包。 如果你打算使用 uvx 运行main imagesorcery-mcp 服务器和需求 clip 功能,您需要确保 clip 包安装在可访问的Python环境中 uvx 可以找到或考虑安装 imagesorcery-mcp 进入由创建的持久环境 python -m venv.

⚙️ 配置MCP客户端

将这些设置添加到MCP客户端。

对于管道安装(推荐):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

对于手动venv安装:

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "/full/path/to/venv/bin/imagesorcery-mcp",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}
If you're using the server in HTTP mode, configure your client to connect to the HTTP endpoint:
"mcpServers": {
    "imagesorcery-mcp": {
      "url": "http://127.0.0.1:8000/mcp", // Use your custom host, port, and path if specified
      "transportType": "http",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}
For Windows

对于管道安装(推荐):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

对于手动venv安装:

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

📦 其他型号

一些工具需要特定的模型才能在 models 目录:

# Download models for the detect tool
download-yolo-models --ultralytics yoloe-11l-seg
download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt
About Model Descriptions

下载模型时,脚本会自动更新 models/model_descriptions.json 文件:

  • 对于Ultralytics型号:描述在中预定义 src/imagesorcery_mcp/scripts/create_model_descriptions.py 并包括有关每个模型的用途、大小和特征的详细信息。

  • 对于抱脸模型:描述会自动从抱脸中心的模型卡中提取。脚本尝试使用模型索引中的模型名称或描述的第一行。

下载模型后,建议查看中的描述 models/model_descriptions.json 并在需要时对其进行调整,以提供有关模型功能和用例的更准确或详细的信息。

运行服务器

ImageSorcery MCP服务器可以在不同模式下运行:

  • STDIO -默认值
  • Streamable HTTP -用于基于web的部署
  • Server-Sent Events (SSE) -适用于依赖于SSE的基于web的部署
About different modes:
  1. STDIO模式(默认) -这是本地MCP客户端的标准模式:

    imagesorcery-mcp
    
  2. 流式HTTP模式 -对于基于web的部署:

    imagesorcery-mcp --transport=streamable-http
    

    使用自定义主机、端口和路径:

    imagesorcery-mcp --transport=streamable-http --host=0.0.0.0 --port=4200 --path=/custom-path
    

可用的运输选项:

  • --transport:在“stdio”(默认)、“可流式传输http”或“sse”之间进行选择
  • --host:指定基于HTTP的传输的主机(默认值:127.0.0.1)
  • --port:指定基于HTTP的传输端口(默认值:8000)
  • --path:指定基于HTTP的传输的端点路径(默认值:/mcp)

🔐 文件访问限制

默认情况下,ImageSorcery MCP不限制文件路径。要将工具限制到特定目录,请设置 IMAGESORCERY_AVAILABLE_PATHS 到一个或多个允许的目录。

使用平台路径列表分隔符(: 在Linux/macOS上, ; 在Windows上)。逗号分隔的值也被接受。

IMAGESORCERY_AVAILABLE_PATHS="/home/user/images:/home/user/output" imagesorcery-mcp

设置此变量后,所有名为 path 或以结尾 _path 必须在允许的目录之一中解析。相对路径, ..,以及 ~ 在比较之前进行归一化。符号链接未解析,因此放置在允许目录中的链接仍可访问。

🔒 隐私和遥测

我们致力于保护您的隐私。ImageSorcery MCP旨在本地运行,确保您的图像和数据保留在您的机器上。

为了帮助我们了解哪些功能最受欢迎并更快地修复错误,我们引入了可选的匿名遥测技术。

  • 默认情况下,它处于禁用状态。 您必须明确选择加入才能启用它。
  • 我们收集的内容: 匿名使用数据。, crop, detect)、应用程序版本、操作系统类型(例如“linux”、“win32”)和工具故障。
  • 我们从不收集的东西: 我们不收集任何个人或敏感信息。这包括图像数据、文件路径、IP地址或任何其他个人身份信息。
  • 如何启用/禁用: 您可以通过设置来控制遥测 enabled = true 或 enabled = false 在 [telemetry] 你的部分 config.toml 文件。

⚙️ 配置服务器

服务器可以使用配置 config.toml 当前目录中的文件。该文件在安装过程中使用默认值自动创建。您可以在此文件中自定义默认工具参数。更多内容 CONFIG.md.

🤝 贡献

Whether you're a 👤 human or an 🤖 AI agent, we welcome your contributions to this project!

目录结构

此存储库的组织如下:

.
├── .gitignore                 # Specifies intentionally untracked files that Git should ignore.
├── pyproject.toml             # Configuration file for Python projects, including build system, dependencies, and tool settings.
├── pytest.ini                 # Configuration file for the pytest testing framework.
├── README.md                  # The main documentation file for the project.
├── setup.sh                   # A shell script for quick setup (legacy, for reference or local use).
├── models/                    # This directory stores pre-trained models used by tools like `detect` and `find`. It is typically ignored by Git due to the large file sizes.
│   ├── model_descriptions.json  # Contains descriptions of the available models.
│   ├── settings.json            # Contains settings related to model management and training runs.
│   └── *.pt                     # Pre-trained model.
├── src/                       # Contains the source code for the 🪄 ImageSorcery MCP server.
│   └── imagesorcery_mcp/       # The main package directory for the server.
│       ├── README.md            # High-level overview of the core architecture (server and middleware).
│       ├── __init__.py          # Makes `imagesorcery_mcp` a Python package.
│       ├── __main__.py          # Entry point for running the package as a script.
│       ├── logging_config.py    # Configures the logging for the server.
│       ├── server.py            # The main server file, responsible for initializing FastMCP and registering tools.
│       ├── middleware.py        # Custom middleware for improved validation error handling.
│       ├── logs/                # Directory for storing server logs.
│       ├── scripts/             # Contains utility scripts for model management.
│       │   ├── README.md        # Documentation for the scripts.
│       │   ├── __init__.py      # Makes `scripts` a Python package.
│       │   ├── create_model_descriptions.py # Script to generate model descriptions.
│       │   ├── download_clip.py # Script to download CLIP models.
│       │   ├── post_install.py  # Script to run post-installation tasks.
│       │   └── download_models.py # Script to download other models (e.g., YOLO).
│       ├── tools/               # Contains the implementation of individual MCP tools.
│       │   ├── README.md        # Documentation for the tools.
│       │   ├── __init__.py      # Makes `tools` a Python package.
│       │   └── *.py           # Implements the tool.
│       ├── prompts/             # Contains the implementation of individual MCP prompts.
│       │   ├── README.md        # Documentation for the prompts.
│       │   ├── __init__.py      # Makes `prompts` a Python package.
│       │   └── *.py           # Implements the prompt.
│       └── resources/           # Contains the implementation of individual MCP resources.
│           ├── README.md        # Documentation for the resources.
│           ├── __init__.py      # Makes `resources` a Python package.
│           └── *.py           # Implements the resource.
└── tests/                     # Contains test files for the project.
    ├── test_server.py         # Tests for the main server functionality.
    ├── data/                  # Contains test data, likely image files used in tests.
    ├── tools/                 # Contains tests for individual tools.
    ├── prompts/               # Contains tests for individual prompts.
    └── resources/             # Contains tests for individual resources.

开发设置

  1. 克隆存储库:
git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Or your fork
cd imagesorcery-mcp
  1. (推荐)创建并激活虚拟环境:
python -m venv venv
source venv/bin/activate # For Linux/macOS
# venv\Scripts\activate    # For Windows
  1. 在可编辑模式下安装软件包以及开发依赖关系:
pip install -e ".[dev]"

这将安装 imagesorcery-mcp 以及来自的所有依赖关系 [project.dependencies] 和 [project.optional-dependencies].dev (包括 build 和 twine).

规则

这些规则适用于所有贡献者:人类和人工智能。

  1. 阅读所有 README.md 项目中的文件。了解项目结构和目的。了解贡献的指导方针。想想它与你的任务有什么关系,以及如何做出相应的改变。

  2. 阅读 pyproject.toml. 注意以下部分: [tool.ruff], [tool.ruff.lint], [project.optional-dependencies] 和 [project]dependencies. 严格遵循中定义的代码样式 pyproject.toml. 坚持中定义的堆栈 pyproject.toml 依赖关系,没有充分的理由,不要添加任何新的依赖关系。

  3. 在新文件和现有文件中编写代码。 如果需要新的依赖关系,请更新 pyproject.toml 并通过安装 pip install -e . 或 pip install -e ".[dev]"。不要直接通过安装 pip install. 查看现有的源代码以获取示例(例如。 src/imagesorcery_mcp/server.py, src/imagesorcery_mcp/tools/crop.py).坚持现有代码的代码风格、命名约定、输入输出数据格式、代码结构、架构等。

  4. 更新相关 README.md 包含您更改的文件。 坚持现有的格式和结构 README.md 文件夹。

  5. 为你的代码编写测试。 查看现有的测试示例(例如。 tests/test_server.py, tests/tools/test_crop.py). 坚持现有测试的代码风格、命名约定、输入和输出数据格式、代码结构、架构等。

  6. 运行测试和检查以确保一切正常:

pytest
ruff check .

如果失败,请修复代码和测试。它是 严格要求 让所有新代码符合linter规则并通过所有测试。

编码提示

  • 在适当的情况下使用类型提示
  • 使用pydantic进行数据验证和序列化

📝 问题?

如果您对此项目有任何疑问、问题或建议,请随时联系:

您还可以在存储库中打开一个问题,以获取错误报告或功能请求。

📜 许可证

该项目根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。