🪄 이미지소서리 MCP

AI 보조원을 위한 ComputerVision 기반 이미지 인식 및 편집 도구의 마법

❌ ImageSorcery MCP 없이

AI 어시스턴트는 이미지 작업 시 다음과 같은 제한을 받습니다.

❌ 이미지를 직접 수정하거나 분석할 수 없습니다.
❌ 이미지 자르기, 크기 조정 또는 처리 기능이 없습니다.
❌ 일부 LLM은 객체를 감지하거나 이미지에서 텍스트를 추출할 수 없습니다.
❌ 시각적 조작 없이 구두 설명으로만 제한됨

✅ ImageSorcery MCP 사용

🪄 ImageSorcery AI 보조원에게 강력한 이미지 처리 기능을 제공합니다.

✅ 정밀하게 이미지를 자르고, 크기를 조정하고, 회전하세요
✅ 이미지에 텍스트와 모양 그리기
✅ 최첨단 모델을 사용하여 객체 감지
✅ OCR을 사용하여 이미지에서 텍스트 추출
✅ 자세한 이미지 메타데이터를 얻으세요
✅ 객체 감지, OCR 등을 위해 다양한 사전 학습된 모델을 사용하세요

AI에게 이미지 작업을 도와달라고 요청하세요.

"반려동물 사진을 frolder photos 폴더에서 pets 폴더로 복사"

"photo.jpg에서 고양이를 찾아 이미지의 높이와 너비를 반으로 잘라 고양이를 중앙에 배치하세요." 😉 힌트: 파일의 전체 경로를 사용하세요.

" foduucom/web-form-ui-field-detection 모델을 사용하여 이 form.jpg 의 양식 필드에 번호를 매기고 설명된 필드 목록으로 form.md 채웁니다." 😉 힌트: 모델과 신뢰도를 지정하세요.

😉 힌트: "imagesorcery 사용"을 추가하여 적절한 도구를 사용하세요.

귀하의 도구는 아래 나열된 여러 도구를 결합하여 귀하의 목표를 달성합니다.

🛠️ 사용 가능한 도구

도구	설명	예시 프롬프트
`crop`	OpenCV의 NumPy 슬라이싱 방식을 사용하여 이미지를 자릅니다.	"내 이미지 'input.png'를 좌표 (10,10)에서 (200,200)까지 잘라서 'cropped.png'로 저장합니다."
`resize`	OpenCV를 사용하여 이미지 크기를 조정합니다	"내 이미지 'photo.jpg'의 크기를 800x600픽셀로 조정하고 'resized_photo.jpg'라는 이름으로 저장합니다."
`rotate`	imutils.rotate_bound 함수를 사용하여 이미지를 회전합니다.	"내 이미지 'photo.jpg'를 45도 회전하여 'rotated_photo.jpg'라는 이름으로 저장합니다."
`draw_texts`	OpenCV를 사용하여 이미지에 텍스트를 그립니다.	"내 이미지 'photo.jpg'의 위치(50,50)에 'Hello World'라는 텍스트를 추가하고 오른쪽 하단에 'Copyright 2023'이라는 텍스트를 추가합니다."
`draw_rectangles`	OpenCV를 사용하여 이미지에 사각형을 그립니다.	"내 이미지 'photo.jpg'에서 (50,50)에서 (150,100)까지 빨간색 사각형을 그리고 (200,150)에서 (300,250)까지 채워진 파란색 사각형을 그립니다."
`get_metainfo`	이미지 파일에 대한 메타데이터 정보를 가져옵니다.	"내 이미지 'photo.jpg'에 대한 메타데이터 정보를 가져옵니다."
`detect`	Ultralytics의 모델을 사용하여 이미지에서 객체를 감지합니다.	"0.4의 신뢰 임계값으로 내 이미지 'photo.jpg'에서 객체를 감지합니다."
`find`	텍스트 설명을 기반으로 이미지에서 객체를 찾습니다.	"신뢰도 임계값 0.4로 내 이미지 'photo.jpg'에 있는 모든 개를 찾으세요"
`get_models`	모델 디렉토리에 있는 사용 가능한 모든 모델을 나열합니다.	"모델 디렉토리에 있는 사용 가능한 모든 모델을 나열합니다"
`ocr`	EasyOCR을 사용하여 이미지에서 광학 문자 인식(OCR)을 수행합니다.	"OCR을 사용하여 영어 이미지 'document.jpg'에서 텍스트를 추출합니다."

😉 힌트: 각 도구에 대한 자세한 정보와 사용 지침은 도구의 /src/imagesorcery_mcp/tools/README.md 에서 확인할 수 있습니다.

🚀 시작하기

요구 사항

Python 3.10 이상
Claude.app , Cline 또는 다른 MCP 클라이언트

설치

지엑스피1

가상 환경을 만들고 활성화합니다(강력히 권장): 모든 구성 요소, 특히 clip 패키지(사후 설치 스크립트를 통해 설치됨)를 안정적으로 설치하려면 uv venv 대신 Python의 기본 제공 venv 모듈을 사용하는 것이 좋습니다 .
python -m venv imagesorcery-mcp source imagesorcery-mcp/bin/activate # For Linux/macOS # source imagesorcery-mcp\Scripts\activate # For Windows
활성화된 가상 환경에 패키지를 설치합니다. pip 또는 uv pip 사용할 수 있습니다.
pip install imagesorcery-mcp # OR, if you prefer using uv for installation into the venv: # uv pip install imagesorcery-mcp
설치 후 스크립트 실행: 이 단계는 매우 중요합니다. 필요한 모델을 다운로드하고 GitHub에서 활성화된 가상 환경에 Python clip 패키지를 설치하려고 시도합니다.
imagesorcery-mcp --post-install

사전 학습된 모델을 저장하기 위해 models 디렉토리(일반적으로 가상 환경의 site-packages 디렉토리 내 또는 전역으로 설치된 경우 사용자별 위치)를 만듭니다.
여기에 초기 models/model_descriptions.json 파일이 생성됩니다.
detect 도구에 필요한 기본 YOLO 모델( yoloe-11l-seg-pf.pt , yoloe-11s-seg-pf.pt , yoloe-11l-seg.pt , yoloe-11s-seg.pt )을 이 models 디렉토리에 다운로드합니다.
Ultralytics의 GitHub 저장소에서 clip Python 패키지를 활성 Python 환경에 직접 설치하려고 합니다 . 이는 find 도구의 텍스트 프롬프트 기능에 필요합니다.
find 도구에 필요한 CLIP 모델 파일을 models 디렉토리에 다운로드합니다.

언제든지 이 프로세스를 실행하여 기본 모델을 복원하고 clip 설치를 시도할 수 있습니다.

uv venv 사용하여 가상 환경 생성: 테스트 결과, uv venv 로 생성된 가상 환경에는 imagesorcery-mcp --post-install 스크립트가 GitHub에서 clip 패키지를 자동으로 설치할 수 있도록 pip 포함되지 않을 수 있습니다( clip 설치 단계에서 "pip라는 이름의 모듈이 없습니다" 오류가 발생할 수 있음). uv venv 사용하는 경우:
1. uv venv 생성하고 활성화하세요.
2. imagesorcery-mcp 설치 : uv pip install imagesorcery-mcp .
3. 활성 uv venv 에 clip 패키지를 수동으로 설치합니다.
  uv pip install git+https://github.com/ultralytics/CLIP.git
4. imagesorcery-mcp --post-install 실행하세요. 모델은 다운로드되지만 clip Python 패키지 설치에 실패할 수 있습니다. 설치 후 스크립트를 통해 clip 자동으로 더 원활하게 설치하려면, 위의 1단계에서 설명한 대로 python -m venv 사용하여 가상 환경을 생성하는 것이 좋습니다.
uvx imagesorcery-mcp --post-install 사용: uvx 사용하여 설치 후 스크립트를 직접 실행하면(예: uvx imagesorcery-mcp --post-install ) clip Python 패키지 설치에 실패할 가능성이 높습니다. 이는 uvx 가 생성하는 임시 환경에 스크립트에서 사용할 수 있는 pip 없기 때문입니다. 모델은 다운로드되지만, 이 명령으로는 clip 패키지가 설치되지 않습니다. uvx 사용하여 기본 imagesorcery-mcp 서버를 실행하고 clip 기능이 필요한 경우, uvx 찾을 수 있는 접근 가능한 Python 환경에 clip 패키지가 설치되어 있는지 확인하거나, python -m venv 로 생성된 영구 환경에 imagesorcery-mcp 를 설치하는 것을 고려해야 합니다.

⚙️ MCP 클라이언트 구성

MCP 클라이언트에 다음 설정을 추가하세요. 설치 후 imagesorcery-mcp 시스템 PATH에 있으면 imagesorcery-mcp 명령으로 직접 사용할 수 있습니다. 그렇지 않은 경우 실행 파일의 전체 경로를 제공해야 합니다.

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp", // Or /full/path/to/venv/bin/imagesorcery-mcp if installed in a venv
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe", // Or C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe if installed in a venv
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

📦 추가 모델

일부 도구의 경우 models 디렉토리에서 특정 모델을 사용할 수 있어야 합니다.

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

모델을 다운로드할 때 스크립트는 자동으로 models/model_descriptions.json 파일을 업데이트합니다.

Ultralytics 모델의 경우: 설명은 src/imagesorcery_mcp/scripts/create_model_descriptions.py 에 미리 정의되어 있으며 각 모델의 목적, 크기, 특성에 대한 자세한 정보를 포함합니다.
Hugging Face 모델의 경우: Hugging Face Hub의 모델 카드에서 설명이 자동으로 추출됩니다. 스크립트는 모델 색인의 모델 이름이나 설명의 첫 줄을 사용하려고 합니다.

모델을 다운로드한 후에는 models/model_descriptions.json 의 설명을 확인하고 필요한 경우 모델의 기능과 사용 사례에 대한 보다 정확하고 자세한 정보를 제공하도록 조정하는 것이 좋습니다.

🤝 기여하기

디렉토리 구조

이 저장소는 다음과 같이 구성되어 있습니다.

.
├── .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.
│       ├── __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.
│       ├── 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      # Import the central logger
│           └── *.py           # Implements the tool.
└── 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.

개발 설정

저장소를 복제합니다.

git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Or your fork
cd imagesorcery-mcp

(권장) 가상 환경을 만들고 활성화하세요.

python -m venv venv
source venv/bin/activate # For Linux/macOS
# venv\Scripts\activate    # For Windows

개발 종속성과 함께 편집 가능한 모드로 패키지를 설치하세요.

pip install -e ".[dev]"

이렇게 하면 imagesorcery-mcp 와 [project.dependencies] 및 [project.optional-dependencies].dev 의 모든 종속성( build 및 twine 포함)이 설치됩니다.

규칙

이러한 규칙은 모든 참여자, 즉 인간과 AI에게 적용됩니다.

프로젝트의 모든 README.md 파일을 읽어보세요. 프로젝트 구조와 목적을 이해하고, 기여 지침을 숙지하세요. 이 지침이 작업과 어떤 관련이 있는지, 그리고 그에 따라 어떻게 수정할지 생각해 보세요.
pyproject.toml 읽어보세요. [tool.ruff] , [tool.ruff.lint] , [project.optional-dependencies] , [project]dependencies 섹션에 주의하세요. pyproject.toml 에 정의된 코드 스타일을 엄격히 준수하세요. pyproject.toml 파일 dependencies에 정의된 스택을 따르고, 정당한 이유 없이 새로운 종속성을 추가하지 마세요.
새 파일과 기존 파일에 코드를 작성하세요. 새로운 종속성이 필요한 경우 pyproject.toml 업데이트하고 pip install -e . 또는 pip install -e ".[dev]" 사용하여 설치하세요. pip install 통해 직접 설치하지 마세요. 기존 소스 코드(예: src/imagesorcery_mcp/server.py , src/imagesorcery_mcp/tools/crop.py )에서 예제를 확인하세요. 기존 코드의 코드 스타일, 명명 규칙, 입출력 데이터 형식, 코드 구조, 아키텍처 등을 준수하세요.
관련 README.md 파일을 변경 사항으로 업데이트하세요. 기존 README.md 파일의 형식과 구조를 그대로 유지하세요.
코드에 대한 테스트를 작성하세요. 기존 테스트에서 예시를 확인하세요(예: tests/test_server.py , tests/tools/test_crop.py ). 기존 테스트의 코드 스타일, 명명 규칙, 입출력 데이터 형식, 코드 구조, 아키텍처 등을 그대로 따르세요.
테스트와 린터를 실행하여 모든 것이 제대로 작동하는지 확인하세요.

pytest
ruff check .

실패할 경우 코드와 테스트를 수정하세요. 모든 새 코드는 linter 규칙을 준수하고 모든 테스트를 통과 해야 합니다 .

코딩 힌트

적절한 경우 유형 힌트를 사용하세요
데이터 검증 및 직렬화를 위해 Pydantic을 사용하세요

📝 질문이 있으신가요?

이 프로젝트에 관한 질문, 문제점 또는 제안 사항이 있으시면 언제든지 문의해 주세요.

프로젝트 작성자: LinkedIn을 통한 titulus
Sunrise Apps CEO: Vlad Karm (LinkedIn)

버그 보고나 기능 요청을 위해 저장소에서 이슈를 열 수도 있습니다.

📜 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다.

🪄 ImageSorcery MCP