Skip to main content
Glama
Sign In
enesjakozh

MCP Image Recognition Server

by mario-andreschak
Verified
GitHub
Python
MIT License
9
  • Linux
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

  • Hosts the MCP server repository, allowing users to clone the codebase for local deployment and configuration

  • Utilizes OpenAI GPT-4 Vision API for image analysis and detailed descriptions from both base64-encoded images and image files

MCP 이미지 인식 서버

Anthropic, OpenAI, Cloudflare Workers AI 비전 API를 사용하여 이미지 인식 기능을 제공하는 MCP 서버입니다. 버전 1.2.1.

저자

원래 이 프로젝트는 @mario-andreschak 가 만들었습니다. 감사합니다!
현재 @zudsniper 가 관리하고 있습니다.

특징

  • Anthropic Claude Vision, OpenAI GPT-4 Vision 또는 Cloudflare Workers AI llava-1.5-7b-hf를 사용한 이미지 설명
  • Claude Desktop, Cursor 및 기타 MCP 호환 클라이언트와의 간편한 통합
  • Docker 배포 지원
  • uvx 설치 지원
  • 다양한 이미지 포맷 지원(JPEG, PNG, GIF, WebP)
  • 구성 가능한 기본 및 대체 공급자
  • Base64 및 파일 기반 이미지 입력 지원
  • Tesseract OCR을 사용한 선택적 텍스트 추출

요구 사항

  • Python 3.8 이상
  • Tesseract OCR(선택 사항) - 텍스트 추출 기능에 필요함
    • Windows: UB-Mannheim/tesseract 에서 다운로드하고 설치하세요.
    • 리눅스: sudo apt-get install tesseract-ocr
    • macOS: brew install tesseract

설치

옵션 1: uvx 사용(Claude Desktop 및 Cursor에 권장)

  1. uv 패키지 관리자를 설치하세요:

지엑스피1

  1. uvx로 패키지를 설치하세요:
uvx install mcp-image-recognition
  1. 구성 섹션에 설명된 대로 환경 파일을 만들고 구성하세요.

옵션 2: Docker 사용

docker pull zudsniper/mcp-image-recognition:latest # Create a .env file first, then run: docker run -it --env-file .env zudsniper/mcp-image-recognition

옵션 3: 소스에서

  1. 저장소를 복제합니다.
git clone https://github.com/zudsniper/mcp-image-recognition.git cd mcp-image-recognition
  1. 환경 파일을 만들고 구성하세요.
cp .env.example .env # Edit .env with your API keys and preferences
  1. 프로젝트를 빌드하세요:
pip install -e .

완성

Claude 데스크톱 통합

  1. Claude > 설정 > 개발자 > 구성 편집 > claude_desktop_config.json 으로 이동하세요.
  2. 인라인 환경 변수를 사용하여 구성을 추가합니다.
{ "mcpServers": { "image-recognition": { "command": "uvx", "args": [ "mcp-image-recognition" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

커서 통합

커서 설정 > MCP 로 이동하여 env 변수와 함께 붙여넣습니다.

VISION_PROVIDER=openai OPENAI_API_KEY=your-api-key OPENAI_MODEL=gpt-4o uvx mcp-image-recognition

Docker 통합

옵션 1: DockerHub 이미지 사용

인라인 환경을 사용하여 Claude Desktop 구성에 다음을 추가하세요.

{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "run", "--rm", "-i", "zudsniper/mcp-image-recognition:latest" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

Cloudflare 구성의 경우:

"env": { "VISION_PROVIDER": "cloudflare", "CLOUDFLARE_API_KEY": "your-api-key", "CLOUDFLARE_ACCOUNT_ID": "your-account-id" }

용법

서버를 직접 실행

pip/uvx로 설치한 경우:

mcp-image-recognition

소스 디렉토리에서:

python -m image_recognition_server.server

Docker 사용:

docker run -it --env-file .env zudsniper/mcp-image-recognition

MCP 검사기를 사용하여 개발 모드를 시작합니다.

npx @modelcontextprotocol/inspector mcp-image-recognition

사용 가능한 도구

  1. describe_image
    • 목적 : 채팅에 직접 업로드된 이미지 분석
    • 입력 : Base64로 인코딩된 이미지 데이터
    • 출력 : 이미지에 대한 자세한 설명
    • 가장 적합 : Claude, Cursor 또는 기타 채팅 인터페이스에 직접 업로드된 이미지
  2. describe_image_from_file
    • 목적 : 파일 시스템에서 로컬 이미지 파일을 처리합니다.
    • 입력 : 이미지 파일 경로
    • 출력 : 이미지에 대한 자세한 설명
    • 가장 적합한 용도 : 파일 시스템 액세스를 통한 로컬 개발
    • 참고 : Docker에서 실행하는 경우 볼륨 매핑이 필요합니다(Docker 파일 액세스 섹션 참조)
  3. describe_image_from_url
    • 목적 : 수동으로 다운로드하지 않고 웹 URL의 이미지 분석
    • 입력 : 공개적으로 접근 가능한 이미지의 URL
    • 출력 : 이미지에 대한 자세한 설명
    • 가장 적합한 대상 : 웹 이미지, 스크린샷 또는 공개 URL이 있는 모든 항목
    • 참고 : 속도 제한을 피하기 위해 브라우저와 유사한 헤더를 사용합니다.

환경 구성

  • ANTHROPIC_API_KEY : Anthropic API 키입니다.
  • OPENAI_API_KEY : OpenAI API 키입니다.
  • CLOUDFLARE_API_KEY : Cloudflare API 키.
  • CLOUDFLARE_ACCOUNT_ID : Cloudflare 계정 ID입니다.
  • VISION_PROVIDER : 주요 비전 제공자( anthropic , openai 또는 cloudflare ).
  • FALLBACK_PROVIDER : 선택적 폴백 공급자입니다.
  • LOG_LEVEL : 로깅 레벨(DEBUG, INFO, WARNING, ERROR).
  • ENABLE_OCR : Tesseract OCR 텍스트 추출을 활성화합니다( true 또는 false ).
  • TESSERACT_CMD : Tesseract 실행 파일의 선택적 사용자 정의 경로입니다.
  • OPENAI_MODEL : OpenAI 모델(기본값: gpt-4o-mini ). 다른 모델에는 OpenRouter 형식을 사용할 수 있습니다(예: anthropic/claude-3.5-sonnet:beta ).
  • OPENAI_BASE_URL : OpenAI API에 대한 선택적 사용자 지정 기본 URL입니다. OpenRouter의 경우 https://openrouter.ai/api/v1 로 설정합니다.
  • OPENAI_TIMEOUT : OpenAI API에 대한 선택적 사용자 정의 시간 초과(초)입니다.
  • CLOUDFLARE_MODEL : Cloudflare Workers AI 모델(기본값: @cf/llava-hf/llava-1.5-7b-hf ).
  • CLOUDFLARE_MAX_TOKENS : 생성할 토큰의 최대 수(기본값: 512 ).
  • CLOUDFLARE_TIMEOUT : Cloudflare API 요청에 대한 시간 초과(초) (기본값: 60 ).

OpenRouter 사용하기

OpenRouter를 사용하면 OpenAI API 형식을 사용하여 다양한 모델에 액세스할 수 있습니다. OpenRouter를 사용하려면 다음 단계를 따르세요.

  1. OpenRouter에서 OpenAI API 키를 얻습니다.
  2. .env 파일에서 OPENAI_API_KEY OpenRouter API 키로 설정합니다.
  3. OPENAI_BASE_URL``https://openrouter.ai/api/v1 로 설정합니다.
  4. OpenRouter 형식(예: anthropic/claude-3.5-sonnet:beta )을 사용하여 OPENAI_MODEL 원하는 모델로 설정합니다.
  5. VISION_PROVIDER``openai 로 설정합니다.

기본 모델

  • 인류학적: claude-3.5-sonnet-beta
  • OpenAI: gpt-4o-mini
  • Cloudflare 작업자 AI: @cf/llava-hf/llava-1.5-7b-hf
  • OpenRouter: OPENAI_MODEL 에서 anthropic/claude-3.5-sonnet:beta 형식을 사용합니다.

개발

개발 설정 가이드

개발 환경 설정

  1. 저장소를 복제합니다.
git clone https://github.com/zudsniper/mcp-image-recognition.git cd mcp-image-recognition
  1. uv로 설정(권장):
# Install uv if not installed pip install uv # Create virtual environment and install deps uv venv uv venv activate uv pip install -e . uv pip install -e ".[dev]"

pip를 이용한 대체 설정:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e . # Or alternatively: pip install -r requirements.txt pip install -r requirements-dev.txt
  1. 환경 구성:
cp .env.example .env # Edit .env with your API keys

VS 코드/DevContainer 개발

  1. 원격 컨테이너 확장 기능으로 VS Code 설치
  2. VS Code에서 프로젝트 폴더를 엽니다.
  3. 메시지가 표시되면 "컨테이너에서 다시 열기"를 클릭하세요.
  4. devcontainer는 모든 종속성이 설치된 상태로 빌드되고 열립니다.

Claude Desktop과 함께 개발 컨테이너 사용

  1. docker compose에 환경 파일 전달:
# Modern Docker Compose V2 syntax docker compose --env-file .env up -d
  1. Claude Desktop 구성에 다음을 추가하세요.
{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "exec", "-i", "mcp-image-recognition-dev", "python", "-m", "image_recognition_server.server" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

로컬에서 변경 사항 테스트

  1. 개발 모드에서 MCP 서버를 실행합니다.
# Install the MCP Inspector if you haven't already npm install -g @modelcontextprotocol/inspector # Start the server with the Inspector npx @modelcontextprotocol/inspector mcp-image-recognition
  1. Inspector는 웹 인터페이스(일반적으로 http://localhost:3000 )를 제공하며 이를 통해 다음을 수행할 수 있습니다.
    • 도구에 요청 보내기
    • 요청/응답 로그 보기
    • 구현과 관련된 문제 디버깅
  2. 테스트용 도구:
    • describe_image 의 경우: base64로 인코딩된 이미지를 제공하세요.
    • describe_image_from_file 의 경우: 로컬 이미지 파일에 대한 경로를 제공합니다.
    • describe_image_from_url 의 경우: 이미지의 URL을 제공하세요.

테스트를 위해 Claude Desktop과 통합

  1. 개발 버전을 사용하도록 Claude Desktop 구성을 임시로 수정하세요.
{ "mcpServers": { "image-recognition": { "command": "python", "args": [ "-m", "image_recognition_server.server" ], "cwd": "/path/to/your/mcp-image-recognition", "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }
  1. 변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.
  2. 대화에서 이미지를 업로드하거나 이미지 URL을 제공하여 테스트하세요.

테스트 실행

모든 테스트를 실행합니다.

run.bat test

특정 테스트 모음을 실행합니다.

run.bat test server run.bat test anthropic run.bat test openai

도커 지원

Docker 이미지를 빌드합니다.

docker build -t mcp-image-recognition .

컨테이너를 실행합니다.

docker run -it --env-file .env mcp-image-recognition

Docker 파일 액세스 제한

Docker에서 MCP 서버를 실행할 때 describe_image_from_file 도구는 컨테이너 내부의 파일에만 액세스할 수 있습니다. 기본적으로 컨테이너는 호스트 시스템의 파일에는 액세스할 수 없습니다. 로컬 파일에 대한 액세스를 활성화하려면 MCP 서버를 구성할 때 디렉터리를 명시적으로 매핑해야 합니다.

중요 참고 사항 : Claude Desktop, Cursor 또는 채팅에 이미지가 업로드되는 다른 플랫폼을 사용하는 경우, 해당 이미지는 Anthropic 서버에 저장되며 파일 시스템 경로를 통해 MCP 서버에 직접 접근할 수 없습니다. 이러한 경우 다음을 수행해야 합니다.

  1. 채팅에 직접 업로드된 이미지의 경우 describe_image 도구(base64로 인코딩된 이미지 사용)를 사용하세요.
  2. 온라인에 호스팅된 이미지에 대해 새로운 describe_image_from_url 도구를 사용하세요.
  3. 로컬 파일의 경우 디렉토리가 Docker 컨테이너에 올바르게 매핑되었는지 확인하세요.

로컬 디렉토리를 Docker에 매핑

Docker 컨테이너가 시스템의 특정 폴더에 액세스할 수 있도록 하려면 볼륨 매핑을 포함하도록 MCP 서버 구성을 수정하세요.

{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/on/host:/path/in/container", "zudsniper/mcp-image-recognition:latest" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

예를 들어, 다운로드 폴더를 매핑하려면 다음을 수행합니다.

  • Windows: -v "C:\\Users\\YourName\\Downloads:/app/images"
  • macOS/Linux: -v "/Users/YourName/Downloads:/app/images"

그런 다음 컨테이너 경로를 사용하여 파일에 액세스합니다: /app/images/your_image.jpg

특허

MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

Cloudflare Workers AI 사용

Cloudflare Workers AI를 이미지 인식에 사용하려면:

  1. Cloudflare 대시보드 에 로그인하고 계정을 선택하세요.
  2. AI > Workers AI 로 이동합니다.
  3. REST API 사용을 선택하고 Workers AI 권한이 있는 API 토큰을 만듭니다.
  4. .env 파일에서 다음을 설정하세요.
    • CLOUDFLARE_API_KEY : Cloudflare API 토큰
    • CLOUDFLARE_ACCOUNT_ID : Cloudflare 계정 ID
    • VISION_PROVIDER : cloudflare 로 설정
    • CLOUDFLARE_MODEL : 선택 사항이며 기본값은 @cf/llava-hf/llava-1.5-7b-hf

AI 어시스턴트와 함께 사용

구성이 완료되면 AI 도우미(예: Claude)는 다음과 같은 방법으로 이미지를 분석할 수 있습니다.

  1. 채팅에 직접 이미지 업로드
  2. 보조자는 자동으로 MCP 서버를 사용하여 이미지를 분석합니다.
  3. 어시스턴트는 비전 API 출력을 기반으로 이미지를 자세히 설명합니다.

이미지 업로드 후 나타나는 프롬프트 예:

Please describe this image in detail.

특정 요구 사항에 맞게 프롬프트를 사용자 정의할 수도 있습니다.

What text appears in this image?

또는

Is there any safety concern in this image?

출시 내역

  • 1.2.1 (2025-03-28): 문서 재구성 및 devcontainer 워크플로 개선
  • 1.2.0 (2025-03-28): httpx 및 브라우저 헤더를 사용한 URL 이미지 페칭 수정, devcontainer 지원 추가
  • 1.1.0 (2025-03-28): 더 나은 선택을 위한 향상된 도구 설명, 최신 버전으로 업데이트된 OpenAI SDK
  • 1.0.1 (2025-03-28): URL 기반 이미지 인식 기능 추가, Docker 문서 개선, 파일 시스템 제한 수정
  • 1.0.0 (2025-03-28): llava-1.5-7b-hf 모델, Docker 지원 및 uvx 호환성을 갖춘 Cloudflare Workers AI 지원이 추가되었습니다.
  • 0.1.2 (2025-02-20): OCR 오류 처리가 개선되었으며 OCR 기능에 대한 포괄적인 테스트 범위가 추가되었습니다.
  • 0.1.1 (2025-02-19): 이미지에서 텍스트를 추출하기 위한 Tesseract OCR 지원 추가(선택 기능)
  • 0.1.0 (2025-02-19): Anthropic 및 OpenAI 비전 지원을 포함한 최초 릴리스

특허

MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

새로운 버전 출시

새 버전을 출시하려면:

  1. pyproject.toml 및 setup.py 의 버전을 업데이트합니다.
  2. release 브랜치에 변경 사항 푸시
  3. GitHub Actions는 자동으로 다음을 수행합니다.
    • 테스트 실행
    • Docker 이미지 빌드 및 푸시
    • PyPI에 게시
    • GitHub 릴리스 만들기

CI/CD에 필요한 저장소 비밀:

  • DOCKERHUB_USERNAME - Docker Hub 사용자 이름
  • DOCKERHUB_TOKEN - Docker Hub 액세스 토큰
  • PYPI_API_TOKEN - PyPI API 토큰

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

Anthropic Claude Vision 및 OpenAI GPT-4 Vision API를 사용하여 이미지 인식 기능을 제공하고, 여러 이미지 형식을 지원하며, Tesseract OCR을 통해 선택적 텍스트 추출 기능을 제공합니다.

  1. Authors
    1. Features
      1. Requirements
        1. Installation
          1. Option 1: Using uvx (Recommended for Claude Desktop and Cursor)
          2. Option 2: Using Docker
          3. Option 3: From Source
        2. Integration
          1. Claude Desktop Integration
          2. Cursor Integration
          3. Docker Integration
        3. Usage
          1. Running the Server Directly
          2. Available Tools
          3. Environment Configuration
          4. Using OpenRouter
          5. Default Models
        4. Development
          1. Development Setup Guide
          2. Running Tests
          3. Docker Support
        5. License
          1. Using Cloudflare Workers AI
        6. Using with AI Assistants
          1. Release History
            1. License
              1. Contributing
                1. Releasing New Versions

              Related Resources

              Appeared in Searches

              ID: lit789bgem