🪄 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系统:```bash
sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx
**对于Docker容器:**
将此行添加到您的Dockerfile中:```dockerfile
RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx
安装
For Cline just copy-paste LLM-INSTALL.md``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 commandpipx install imagesorcery-mcp3. Run commandimagesorcery-mcp --post-install4. Create or modify *MCP-configuration file*.
5. Add theimagesorcery-mcpserver configuration to themcpServersobject in the *MCP-configuration file*"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}6. Prompt the user for permission and enable telemetry by callingconfig(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):
0. **安装管道(如果尚未安装):**```bash
# 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
- 使用pipx安装ImageSorcery MCP:```bash
pipx install imagesorcery-mcp
1. **运行安装后脚本:**
这一步至关重要。它下载所需的模型并尝试安装 `clip` GitHub上的Python包。```bash
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.
- 创建并激活虚拟环境:```bash
python -m venv imagesorcery-mcp
source imagesorcery-mcp/bin/activate # For Linux/macOS
source imagesorcery-mcp\Scripts\activate # For Windows
1. **将软件包安装到激活的虚拟环境中:**
您可以使用 `pip` 或 `uv pip`.```bash
pip install imagesorcery-mcp
# OR, if you prefer using uv for installation into the venv:
# uv pip install imagesorcery-mcp
- 运行安装后脚本:
这一步至关重要。它下载所需的模型并尝试安装clipPython包从GitHub进入活动虚拟环境。```bash
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`:```bash
uv pip install git+https://github.com/ultralytics/CLIP.git
- 跑
imagesorcery-mcp --post-install。这将下载模型,但可能无法安装clipPython包。
实现更平稳的自动化clip通过安装后脚本进行安装,使用python -m venv(如上述步骤1所述)是创建虚拟环境的推荐方法。
- 使用
uvx imagesorcery-mcp --post-install:
直接使用以下命令运行安装后脚本uvx(例如。,uvx imagesorcery-mcp --post-install)可能无法安装clipPython包。这是因为由以下因素创建的临时环境uvx通常没有pip以脚本可以使用的方式提供。模型将被下载,但clip此命令不会安装程序包。
如果你打算使用uvx运行mainimagesorcery-mcp服务器和需求clip功能,您需要确保clip包安装在可访问的Python环境中uvx可以找到或考虑安装imagesorcery-mcp进入由创建的持久环境python -m venv.
⚙️ 配置MCP客户端
将这些设置添加到MCP客户端。
对于管道安装(推荐):```json
"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安装:**```json
"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:```json
"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
**对于管道安装(推荐):**```json
"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安装:```json
"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` 目录:```bash
# 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:
- STDIO模式(默认) -这是本地MCP客户端的标准模式:```bash
imagesorcery-mcp
1. **流式HTTP模式** -对于基于web的部署:```bash
imagesorcery-mcp --transport=streamable-http
使用自定义主机、端口和路径:```bash
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.
开发设置
- 克隆存储库:```bash
git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Or your fork
cd imagesorcery-mcp
2. (推荐)创建并激活虚拟环境:```bash
python -m venv venv
source venv/bin/activate # For Linux/macOS
# venv\Scripts\activate # For Windows
- 在可编辑模式下安装软件包以及开发依赖关系:```bash
pip install -e ".[dev]"
这将安装 `imagesorcery-mcp` 以及来自的所有依赖关系 `[project.dependencies]` 和 `[project.optional-dependencies].dev` (包括 `build` 和 `twine`).
### 规则
这些规则适用于所有贡献者:人类和人工智能。
0. 阅读所有 `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. 运行测试和检查以确保一切正常:```bash
pytest
ruff check .
如果失败,请修复代码和测试。它是 严格要求 让所有新代码符合linter规则并通过所有测试。
编码提示
- 在适当的情况下使用类型提示
- 使用pydantic进行数据验证和序列化
📝 问题?
如果您对此项目有任何疑问、问题或建议,请随时联系:
- 项目作者: 名义 通过LinkedIn
- Sunrise Apps首席执行官: 弗拉德·卡姆 通过LinkedIn
您还可以在存储库中打开一个问题,以获取错误报告或功能请求。
📜 许可证
该项目根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。
