🪄 ImageSorcery MCP

🪄 ImageSorcery MCP

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

官方网站： imagemagicy.net

 ](https://pepy.tech/projects/imagesorcery-mcp)

✅ 使用ImageSorcery MCP

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

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

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

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

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

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

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

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

🛠️ 可用工具

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

📚 可用资源

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

💬 可用提示

😉 _提示： 每个提示的详细信息和使用说明可以在提示中找到 /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的推荐方式，因为它会自动处理虚拟环境的创建和管理，使安装过程更加简单。

1. 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

1. 运行安装后脚本：

这一步至关重要。它下载所需的模型并尝试安装 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

1. 将软件包安装到激活的虚拟环境中：

您可以使用 pip 或 uv pip.

   pip install imagesorcery-mcp
   # OR, if you prefer using uv for installation into the venv:
   # uv pip install imagesorcery-mcp

1. 运行安装后脚本：

这一步至关重要。它下载所需的模型并尝试安装 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. 1. 安装 imagesorcery-mcp: uv pip install imagesorcery-mcp. 1. 手动安装 clip 打包到您的活动 uv venv:

     uv pip install git+https://github.com/ultralytics/CLIP.git

1. 跑 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

1. 流式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旨在本地运行，确保您的图像和数据保留在您的机器上。

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

• 默认情况下，它处于禁用状态。 您必须明确选择加入才能启用它。
• 我们收集的内容： 匿名使用数据。， 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 项目中的文件。了解项目结构和目的。了解贡献的指导方针。想想它与你的任务有什么关系，以及如何做出相应的改变。

1. 阅读 pyproject.toml.

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

1. 在新文件和现有文件中编写代码。

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

1. 更新相关 README.md 包含您更改的文件。

坚持现有的格式和结构 README.md 文件夹。

1. 为你的代码编写测试。

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

1. 运行测试和检查以确保一切正常：

pytest
ruff check .

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

编码提示

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

📝 问题？

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

• 项目作者： 名义 通过LinkedIn
• Sunrise Apps首席执行官： 弗拉德·卡姆 通过LinkedIn

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

📜 许可证

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