shehdrbs123/mcp-image-crawler

MCP Image Crawler

Node.js 기반 MCP(Model Context Protocol) 서버로, CC0, CC BY 등 허용 가능한 라이선스의 로열티 프리 이미지를 웹 크롤링으로 수집하고 HTML에서 직접 사용 가능한 이미지 URL을 제공합니다.

🌟 주요 특징

• 윤리적 크롤링: robots.txt 준수, 적절한 요청 간격 유지
• 라이선스 검증: CC0, CC BY, Pixabay License 등 허용 라이선스만 수집
• 직접 이미지 URL: HTML <img> 태그에서 바로 사용 가능한 안정적인 URL 제공
• 자동 출처 표기: 라이선스별 적절한 attribution 자동 생성
• 다중 소스 지원: Wikimedia Commons, Pixabay, StockVault 등

🚀 빠른 시작

설치

# 저장소 클론
git clone https://github.com/shehdrbs123/mcp-image-crawler.git
cd mcp-image-crawler

# 의존성 설치
npm install

# 환경 변수 설정
cp .env.example .env
# .env 파일을 편집하여 필요한 설정 조정

# 서버 시작
npm start

환경 변수 설정

프로젝트를 사용하기 전에 환경 변수를 설정해야 합니다:

1단계: 환경 파일 생성

cp .env.example .env

2단계: 설정 변경

.env 파일을 편집하여 필요에 따라 다음 설정들을 조정하세요:

🔧 기본 서버 설정

# MCP 서버 기본 정보
MCP_SERVER_NAME=mcp-image-crawler
MCP_SERVER_VERSION=1.0.0
SERVER_PORT=3000

🕰️ 크롤링 동작 설정

# 요청 간 대기 시간 (밀리초) - 윤리적 크롤링을 위해 중요!
DEFAULT_REQUEST_DELAY=2000

# 동시 실행 요청 수 - 서버 부하 방지
MAX_CONCURRENT_REQUESTS=2

# 요청 타임아웃 (밀리초)
REQUEST_TIMEOUT=30000

# 실패 시 재시도 횟수
MAX_RETRIES=3

🚦 속도 제한 설정

# 분당 최대 요청 수
RATE_LIMIT_REQUESTS_PER_MINUTE=30

# 버스트 요청 허용 수
RATE_LIMIT_BURST=5

🔍 User Agent 설정

# 웹사이트에서 크롤러를 식별할 수 있도록 명확한 User Agent 설정
USER_AGENT=Mozilla/5.0 (compatible; MCPImageCrawler/1.0; +https://github.com/shehdrbs123/mcp-image-crawler)

📝 로깅 설정

# 로그 레벨: debug, info, warn, error
LOG_LEVEL=info

# 로그 포맷: json, text
LOG_FORMAT=json

# 로그 파일 경로
LOG_FILE=logs/crawler.log

🖼️ 이미지 검증 설정

# 최소 이미지 해상도
MIN_IMAGE_WIDTH=800
MIN_IMAGE_HEIGHT=600

# 최대 파일 크기 (MB)
MAX_IMAGE_SIZE_MB=10

# 지원하는 이미지 포맷
SUPPORTED_FORMATS=jpg,jpeg,png,webp,svg

⚖️ 라이선스 필터링

# 허용할 라이선스 유형 (쉼표로 구분)
ALLOWED_LICENSES=CC0,CC BY,CC BY-SA,Pixabay License

# 출처 표기 필수 여부
REQUIRE_ATTRIBUTION=false

# 상업적 사용 가능한 이미지만 수집
COMMERCIAL_USE_ONLY=true

📚 사이트별 URL 설정

# Wikimedia Commons
WIKIMEDIA_BASE_URL=https://commons.wikimedia.org
WIKIMEDIA_SEARCH_URL=https://commons.wikimedia.org/w/api.php

# Pixabay
PIXABAY_BASE_URL=https://pixabay.com
PIXABAY_SEARCH_URL=https://pixabay.com/images/search

# StockVault
STOCKVAULT_BASE_URL=https://www.stockvault.net
STOCKVAULT_SEARCH_URL=https://www.stockvault.net/search

🔄 캐시 설정 (선택사항)

# 캐시 사용 여부
ENABLE_CACHE=false

# 캐시 유지 시간 (초)
CACHE_TTL=3600

# 최대 캐시 항목 수
CACHE_MAX_SIZE=1000

환경 변수 사용 팁

🎯 추천 설정 (일반 사용)

DEFAULT_REQUEST_DELAY=2000
MAX_CONCURRENT_REQUESTS=2
RATE_LIMIT_REQUESTS_PER_MINUTE=30
LOG_LEVEL=info
MIN_IMAGE_WIDTH=800
MIN_IMAGE_HEIGHT=600
COMMERCIAL_USE_ONLY=true

⚡ 빠른 테스트용 설정

DEFAULT_REQUEST_DELAY=1000
MAX_CONCURRENT_REQUESTS=3
RATE_LIMIT_REQUESTS_PER_MINUTE=60
LOG_LEVEL=debug

🛡️ 보수적/안전한 설정

DEFAULT_REQUEST_DELAY=3000
MAX_CONCURRENT_REQUESTS=1
RATE_LIMIT_REQUESTS_PER_MINUTE=20
REQUEST_TIMEOUT=45000

⚠️ 주의사항:

• DEFAULT_REQUEST_DELAY를 너무 낮게 설정하면 웹사이트에서 차단될 수 있습니다
• MAX_CONCURRENT_REQUESTS를 높이면 빠르지만 서버 부하를 증가시킵니다
• 라이선스 설정을 변경할 때는 법적 요구사항을 확인하세요

🔧 MCP 설정 및 사용법

Claude Desktop 설정

이 도구를 Claude Desktop에서 사용하려면 MCP 설정이 필요합니다:

1단계: Claude Desktop MCP 설정 파일 찾기

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2단계: 설정 파일 편집

설정 파일에 다음 내용을 추가하세요:

{
  "mcpServers": {
    "image-crawler": {
      "command": "node",
      "args": ["C:/path/to/mcp-image-crawler/src/server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

⚠️ 중요: C:/path/to/mcp-image-crawler/src/server.js를 실제 프로젝트 경로로 변경하세요!

3단계: Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 종료하고 다시 시작하세요.

4단계: 연결 확인

Claude에서 다음과 같이 테스트해보세요:

"이미지 크롤러가 제대로 작동하는지 테스트해줘"
"고양이 사진 3개 찾아줘"

사용 예시

MCP가 정상적으로 설정되면 Claude에서 자연어로 요청할 수 있습니다:

🔍 이미지 검색

"프레젠테이션용 비즈니스 이미지 5개 찾아줘"
"고해상도 자연 풍경 사진을 검색해줘"
"CC0 라이선스의 음식 사진들을 찾아줘"

✅ URL 검증

"이 이미지 URL들이 유효한지 확인해줘: [URL1, URL2]"
"모든 이미지가 제대로 로드되는지 체크해줘"

📊 메타데이터 추출

"이 이미지의 라이선스 정보를 알려줘"
"해상도와 파일 크기를 확인해줘"
"어트리뷰션을 자동으로 생성해줘"

🎯 지원 사이트

🛡️ 윤리적 크롤링 원칙

1. robots.txt 준수: 모든 사이트의 robots.txt 사전 확인
2. 요청 간격 유지: 사이트당 최소 1-2초 간격
3. 명확한 식별: User-Agent 헤더에 프로젝트 정보 포함
4. 부하 제한: 동시 요청 수 제한 및 백오프 전략
5. 라이선스 존중: 허용된 라이선스의 이미지만 수집

🔍 문제 해결

환경 변수 관련 문제

Q: .env 파일이 로드되지 않아요 A: 다음을 확인해주세요:

1. .env 파일이 프로젝트 루트 디렉토리에 있는지 확인
2. 파일 권한이 올바른지 확인
3. 환경 변수 이름에 공백이나 특수문자가 없는지 확인

Q: 크롤링이 너무 느려요 A: .env에서 다음 값들을 조정해보세요:

DEFAULT_REQUEST_DELAY=1000  # 2000에서 1000으로 감소
MAX_CONCURRENT_REQUESTS=3   # 2에서 3으로 증가

Q: 웹사이트에서 차단당하는 것 같아요 A: 더 보수적인 설정을 사용하세요:

DEFAULT_REQUEST_DELAY=3000  # 대기 시간 증가
MAX_CONCURRENT_REQUESTS=1   # 동시 요청 수 감소

MCP 연결 문제

Q: Claude Desktop에서 이미지 크롤러를 인식하지 못해요 A: 다음을 확인해주세요:

1. claude_desktop_config.json 파일 경로가 올바른지 확인
2. JSON 문법이 올바른지 확인 (컴마, 중괄호 등)
3. args 배열의 절대 경로가 정확한지 확인
4. Claude Desktop 완전 재시작

Q: "MCP server failed to start" 오류가 나요 A: 다음을 시도해보세요:

# 수동으로 서버 테스트
cd mcp-image-crawler
node src/server.js

Q: 경로를 어떻게 설정해야 하나요? A: 절대 경로를 사용하세요:

• Windows: "C:/Users/YourName/mcp-image-crawler/src/server.js"
• macOS/Linux: "/Users/YourName/mcp-image-crawler/src/server.js"

📄 라이선스

이 프로젝트는 MIT 라이선스하에 배포됩니다. 자세한 내용은 파일을 참조하세요.

Made with ❤️ for the MCP community