Evomi MCP Server

Evomi의 프록시 및 웹 스크래핑 API를 위한 Model Context Protocol (MCP) 서버입니다. 이 서버는 Claude와 같은 AI 어시스턴트에게 프록시 계정에 대한 직접 액세스(자격 증명, 연결 문자열, 지역 타겟팅, 사용량, 세션 회전)를 제공하며, 사이트를 크롤링하고 구조화된 데이터를 추출할 수 있는 완전한 스크래핑 도구 모음도 함께 제공합니다.

기본적으로 39개의 도구가 있으며, EVOMI_ENABLE_SPENDING=1로 설정하면 40개입니다.

기능

프록시 및 계정 관리

• 프록시 자격 증명 - 계정의 각 제품에 대한 사용자 이름과 비밀번호

• 연결 문자열 - 지역 타겟팅 및 세션 고정 문자열, 확인용 curl 명령 포함

• 대량 프록시 목록 - 호출당 최대 50개 엔드포인트

• 지역 타겟팅 - 제품이 실제로 제공하는 국가, 지역, 도시 및 ISP 검색

• 사용량 및 잔액 - 24시간, 3일, 7일 동안의 대역폭(총계 및 버킷별)

• 세션 제어 - 고정 세션을 새 종료 IP로 회전

• 브라우저 프로필 - 저장된 핑거프린트 프로필 목록 및 옵트인을 통한 추가 주문

• 서비스 액세스 - 스크레이퍼 및 브라우저 크레딧, 동시성, 엔드포인트

웹 스크래핑

• 단일 페이지 스크래핑 - 자동 JavaScript 감지로 모든 URL 스크래핑

• 웹사이트 크롤링 - 깊이 제어가 가능한 다중 페이지 크롤링

• URL 검색 - 사이트맵, CommonCrawl 또는 사이트 내 크롤링을 통한 URL 찾기

• 도메인 검색 - 웹 검색을 통한 도메인 찾기

• AI 기반 추출 - AI를 사용하여 페이지에서 구조화된 데이터 추출

• 대화형 에이전트 - 스크래핑 작업을 위한 자연어 인터페이스

• 구성 관리 - 스크래핑 구성 저장 및 재사용

• 스키마 관리 - 추출 스키마 정의 및 테스트

• 스토리지 구성 - 스크래핑된 데이터의 클라우드 스토리지 관리

• 예약 작업 - 일정에 따라 스크래핑 자동화

설치

pip install evomi-mcp

Python 3.10 이상이 필요합니다. 이 서버는 mcp SDK의 두 주요 버전(>=1.8.0,<3)에서 모두 실행되므로, 이미 1.x로 고정된 환경은 물론, 2.x로 의존성이 해결되는 새 환경에도 설치할 수 있습니다.

evomi-mcp --help를 실행하면 읽어들이는 환경 변수를 확인할 수 있고, evomi-mcp --version을 실행하면 설치된 버전을 확인할 수 있습니다. 인수 없이 실행하면 stdio를 통해 MCP를 사용하며, 이것이 MCP 클라이언트가 이 서버를 시작하는 방식입니다.

구성

자격 증명 하나면 충분합니다:

export EVOMI_PUBLIC_API_KEY="your-public-api-key"

개인 계정의 경우 설정 > API에서, 팀 계정의 경우 설정 > 팀에서 가져옵니다. 이 키는 프록시 및 계정 도구를 직접 인증하며, 스크래핑 도구는 계정의 스크래퍼 키로 인증합니다. 서버는 첫 번째 스크래핑 호출 시 Public API에서 이 키를 읽어 프로세스 메모리에 보관합니다. 이 키는 디스크에 기록되지 않으며 도구 출력에 나타나지 않습니다.

특정 변수가 설정되면 EVOMI_API_KEY보다 우선합니다. 스크래퍼 키만 설정해도 작동하지만, 그 경우 프록시 및 계정 도구도 EVOMI_PUBLIC_API_KEY가 필요합니다. 하나의 키로 두 API를 모두 처리할 수 없기 때문입니다.

선택적 설정:

export EVOMI_BASE_URL="https://scrape.evomi.com"   # scraper API, default
export EVOMI_PUBLIC_BASE_URL="https://api.evomi.com"  # public API, default
export EVOMI_HIDE_PROXY_PASSWORDS=1  # mask every proxy password and service API key
export EVOMI_ENABLE_SPENDING=1  # register the tools that spend account balance

도구 출력의 자격 증명

get_proxy_credentials, build_proxy_connection_string, generate_proxy_list는 실제 프록시 비밀번호를 반환하며, 이것이 이 도구들의 목적입니다. get_api_access는 include_api_key로 요청하면 서비스 API 키를 반환합니다. 그 외 모든 도구는 잔액, 엔드포인트, 사용량 및 타겟팅 데이터만 반환합니다.

세 가지가 이를 제한합니다. 이 네 도구는 설명에 직접 요청하지 않는 한 값을 다시 말하지 말라는 지침을 포함합니다. MCP 사양에는 민감한 결과에 대한 주석이 없으므로 설명이 모델에 도달하는 유일한 채널입니다. generate_proxy_list와 build_proxy_connection_string은 호출당 최대 50개 항목을 반환하며, 이는 Public API가 허용하는 500개보다 훨씬 적습니다. 더 큰 요청은 잘라내지 않고 거부합니다. 그리고 EVOMI_HIDE_PROXY_PASSWORDS=1은 공개를 완전히 차단합니다:

거부하는 두 도구는 출력 전체가 자격 증명이기 때문입니다. 마스킹된 비밀번호가 있는 연결 문자열은 연결할 수 없습니다. 거부 메시지는 자격 증명 없이 게이트웨이 호스트 이름, 포트 및 타겟팅 값을 제공하는 list_proxy_products와 list_proxy_targeting_options를 안내하며, 모델이 보는 설명도 변경됩니다.

EVOMI_ENABLE_SPENDING=1은 반대로, 비용이 드는 하나의 도구에 대한 옵트인입니다. 이 값이 없으면 order_browser_profile은 전혀 등록되지 않으므로 연결된 모델은 이 도구를 볼 수 없습니다.

도구 주석

모든 도구는 MCP 사양의 네 가지 힌트를 모두 설정합니다. destructiveHint와 openWorldHint는 기본값이 true이므로, 이를 생략한 도구는 잠재적으로 파괴적이고 무한한 외부 세계에 도달하는 것으로 스스로를 표시합니다.

openWorldHint는 호출자가 선택한 주소에 도달하는 도구(scrape_url, crawl_website, map_website, search_domains, agent_request, 그리고 설명하는 페이지를 기준으로 검증하는 스키마 및 구성 도구)에 대해 true이고, Evomi 자체 엔드포인트와만 통신하는 모든 도구에 대해서는 false입니다. readOnlyHint는 무언가를 생성, 업데이트, 삭제, 전환, 회전 또는 주문하는 도구에 대해 false입니다. rotate_proxy_session과 order_browser_profile의 MUTATING 접두사는 설명에도 포함되어 있습니다. 설명은 모든 모델에 도달하지만 주석은 이를 읽는 클라이언트에만 도달하기 때문입니다.

Claude Desktop 사용법

Claude Desktop 구성(~/Library/Application Support/Claude/claude_desktop_config.json, macOS)에 추가하세요:

{
  "mcpServers": {
    "evomi": {
      "command": "evomi-mcp",
      "env": {
        "EVOMI_PUBLIC_API_KEY": "your-public-api-key"
      }
    }
  }
}

또는 소스에서 설치한 경우:

{
  "mcpServers": {
    "evomi": {
      "command": "python",
      "args": ["-m", "evomi_mcp.server"],
      "env": {
        "EVOMI_PUBLIC_API_KEY": "your-public-api-key"
      }
    }
  }
}

사용 가능한 도구

프록시 및 계정 (9개 도구, Evomi Public API, + 1개 옵트인)

스크래핑 작업 (6개 도구)

구성 관리 (6개 도구)

스키마 관리 (6개 도구)

스토리지 관리 (4개 도구)

스케줄 관리 (도구 7개)

계정 (도구 1개)

도구 예시

스크레이핑

// Basic scrape
{"url": "https://example.com"}

// AI extraction
{"url": "https://example.com/products", "ai_enhance": true, "ai_prompt": "Extract product names and prices"}

// Browser mode with actions
{"url": "https://example.com", "mode": "browser", "js_instructions": [{"click": ".accept-cookies"}, {"wait": 1000}]}

크롤링

// Basic crawl
{"domain": "example.com", "max_urls": 50}

// With URL filter
{"domain": "example.com", "url_pattern": "/products/", "depth": 3}

도메인 검색

// Find domains
{"query": "best e-commerce sites for electronics", "max_urls": 20, "region": "us-en"}

// Up to 10 queries in one call, max_urls applying to each
{"query": ["online bookstores", "book shops UK"], "max_urls": 50}

구성 관리

// Create config
{"name": "Product Scraper", "config": {"mode": "browser", "output": "markdown"}}

// Generate config with AI
{"name": "Amazon Scraper", "prompt": "Scrape product title, price, and reviews from Amazon"}

스케줄링

// Create daily schedule
{"name": "Daily Prices", "config_id": "cfg_abc123", "interval_minutes": 1440, "start_time": "09:00"}

크레딧

스크레이핑 작업은 크레딧을 소비하며, 호출 비용은 실행 모드와 포함된 옵션에 따라 달라집니다. 현재 요금은 docs.evomi.com에서 확인할 수 있으며, get_api_access는 계정의 잔액을 보고합니다.

각 스크레이핑 응답에는 credits_used와 credits_remaining이 포함되어 있어 호출 비용을 해당 결과에서 바로 확인할 수 있습니다.

개발

설정

pip install -e ".[dev]"

서버 직접 실행

evomi-mcp
# or
python -m evomi_mcp.server

테스트

pytest

테스트 스위트는 mcp의 두 메이저 버전 모두에서 실행되며, CI는 지원되는 Python 버전 전체에서 각각 실행합니다.

릴리스

버전은 pyproject.toml과 src/evomi_mcp/__init__.py 양쪽에 선언되어 있으며, 두 값이 일치하지 않으면 CI가 실패합니다. vX.Y.Z 태그가 붙은 GitHub Release를 게시하면 아티팩트를 빌드하고, 빌드된 wheel에 대해 테스트 스위트를 실행한 후 Trusted Publishing을 통해 PyPI에 업로드하므로 어디에도 토큰이 필요 없습니다.

링크

• Evomi 웹사이트

• Evomi 대시보드

• API 문서

라이선스

MIT — LICENSE를 참조하세요.