Oxylabs

Oxylabs MCP 서버

AI 모델과 실제 웹 사이의 누락된 연결 고리: 하나의 API로 모든 사이트에서 깔끔하고 구조화된 데이터를 제공합니다.

---

📖 개요

Oxylabs MCP 서버는 AI 모델과 웹 사이의 브리지를 제공합니다. 이를 통해 모든 URL을 스크래핑하고, JavaScript가 많이 사용된 페이지를 렌더링하며, AI 사용을 위해 콘텐츠를 추출하고 형식화하며, CAPTCHA를 관리하고, 195개 이상의 국가에서 지리적으로 제한된 웹 데이터에 접근할 수 있습니다.

이 서버는 AI 어시스턴트를 외부 도구 및 데이터에 연결하기 위한 개방형 표준인 Model Context Protocol (MCP)을 기반으로 구축되었습니다.

🛠️ MCP 도구

Oxylabs MCP는 함께 또는 독립적으로 사용할 수 있는 두 가지 도구 세트를 제공합니다:

Oxylabs Web Scraper API 도구

1. universal_scraper: 모든 URL을 스크래핑하며, 선택적으로 JavaScript 렌더링, 지리적 타겟팅, Markdown/HTML/링크 출력을 지원합니다;
2. google_search_scraper: Google 검색 결과를 추출하며, 선택적으로 구조화된 JSON으로 파싱합니다;
3. amazon_search_scraper: Amazon 검색 결과 페이지를 스크래핑하며, 선택적으로 구조화된 JSON으로 파싱합니다;
4. amazon_product_scraper: 개별 Amazon 제품 페이지에서 데이터를 추출합니다.

Oxylabs AI Studio 도구

5. ai_scraper: AI 기반 추출로 모든 URL에서 콘텐츠를 스크래핑하며, JSON, CSV, Markdown 또는 TOON 형식으로 제공합니다;
6. ai_crawler: 프롬프트를 기반으로 시작 URL에서 웹사이트를 크롤링하고 여러 페이지에 걸쳐 데이터를 수집합니다;
7. ai_browser_agent: 프롬프트를 기반으로 실제 브라우저를 제어합니다 — 탐색, 클릭, 양식 작성 — 결과를 반환합니다;
8. ai_search: 웹을 검색하고 선택적으로 각 결과의 Markdown 콘텐츠를 반환합니다;
9. ai_map: 키워드 또는 프롬프트로 필터링된 웹사이트의 URL을 매핑합니다;
10. generate_schema: 위의 AI 도구와 함께 구조화된 추출을 위한 OpenAPI 형식 JSON 스키마를 생성합니다.

✅ 사전 요구 사항

시작하기 전에 다음 중 하나 이상이 있는지 확인하세요:

• Oxylabs Web Scraper API 계정: Oxylabs에서 사용자 이름과 비밀번호를 얻으세요 (1주 무료 체험 가능);
• Oxylabs AI Studio API 키: Oxylabs AI Studio에서 API 키를 얻으세요 (1000 크레딧 무료).

로컬에서 서버를 실행하려면 (아래 옵션 2) uv 패키지 관리자도 필요합니다:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

📦 구성

서버를 사용하는 두 가지 방법이 있습니다: 호스팅 인스턴스에 연결하거나 (설치 불필요) 환경 변수에 자격 증명을 넣어 로컬에서 실행하는 것입니다.

옵션 1: 호스팅 서버 (설치 불필요)

Oxylabs는 다음 주소에서 호스팅 MCP 서버를 실행합니다:

https://mcp.oxylabs.io/mcp

자격 증명은 요청 헤더로 전달됩니다:

자격 증명	헤더
Web Scraper API	Authorization: Basic <base64(username:password)>
Web Scraper API (대안)	X-Oxylabs-Username 및 X-Oxylabs-Password
AI Studio	X-Oxylabs-AI-Studio-Api-Key

Claude Code로 설정:

claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"

Cursor 또는 사용자 지정 헤더를 지원하는 원격 MCP 서버를 지원하는 모든 클라이언트로 설정:

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://mcp.oxylabs.io/mcp",
      "headers": {
        "Authorization": "Basic <base64 of username:password>",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

서버는 Smithery에도 등록되어 있습니다.

참고: 원격 서버에 OAuth만 지원하는 클라이언트 (예: claude.ai 웹 UI에서 사용자 지정 커넥터 추가)는 아직 헤더를 전달할 수 없습니다 — OAuth 로그인은 로드맵에 있습니다. 그동안 해당 클라이언트에서는 아래의 로컬 설정을 사용하세요.

옵션 2: 로컬 실행

환경 변수

Oxylabs MCP 서버는 다음 환경 변수를 지원합니다:

이름	설명	기본값
OXYLABS_USERNAME	Oxylabs Web Scraper API 사용자 이름
OXYLABS_PASSWORD	Oxylabs Web Scraper API 비밀번호
OXYLABS_AI_STUDIO_API_KEY	Oxylabs AI Studio API 키
LOG_LEVEL	클라이언트에 반환되는 로그의 로그 수준	INFO

제공된 자격 증명에 따라 서버는 해당 도구를 자동으로 노출합니다:

• OXYLABS_USERNAME 및 OXYLABS_PASSWORD만 제공된 경우, 서버는 Web Scraper API 도구를 노출합니다;
• OXYLABS_AI_STUDIO_API_KEY만 제공된 경우, 서버는 AI Studio 도구를 노출합니다;
• 세 가지 모두 제공된 경우, 서버는 모든 도구를 노출합니다.

❗ 중요: 실제 자격 증명이 있는 환경 변수만 설정하세요. 자리 표시자 값을 남기면 작동하지 않는 도구가 노출됩니다.

uvx로 구성

PyPI의 패키지를 설치하고 자동으로 실행합니다:

{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "YOUR_USERNAME",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD",
        "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

로컬 체크아웃으로 구성

개발에 유용합니다 — 이 저장소의 로컬 클론에서 서버를 실행합니다:

{
  "mcpServers": {
    "oxylabs": {
      "command": "uv",
      "args": [
        "--directory",
        "/<absolute-path-to-folder>/oxylabs-mcp",
        "run",
        "oxylabs-mcp"
      ],
      "env": {
        "OXYLABS_USERNAME": "YOUR_USERNAME",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD",
        "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

원격 HTTP 서버로 실행 (자체 호스팅)

서버는 MCP 스트리밍 가능 HTTP 전송도 지원합니다. 다음으로 시작하세요:

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp

HTTP 전송을 사용하면 자격 증명은 환경 변수 대신 요청별로 전달됩니다:

자격 증명	전달 방법
Web Scraper API	Authorization: Basic <base64(username:password)> (표준 HTTP Basic 인증)
Web Scraper API (대안)	X-Oxylabs-Username 및 X-Oxylabs-Password 헤더
AI Studio	X-Oxylabs-AI-Studio-Api-Key 헤더

예제 클라이언트 구성:

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://your-host:8000/mcp",
      "headers": {
        "Authorization": "Basic <base64 of username:password>",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

제공된 자격 증명과 관계없이 모든 도구가 항상 나열됩니다; 필요한 자격 증명 없이 도구를 호출하면 정확히 무엇을 구성해야 하는지 설명하는 오류 메시지가 반환됩니다.

Claude Desktop으로 설정

Claude → 설정 → 개발자 → 구성 편집으로 이동하여 위 구성 중 하나를 claude_desktop_config.json 파일에 추가하세요.

Cursor AI로 설정

Cursor → 설정 → Cursor 설정 → MCP로 이동하세요. 새 전역 MCP 서버 추가를 클릭하고 위 구성 중 하나를 추가하세요.

📝 로깅

서버는 notification/message 이벤트에서 도구 호출에 대한 추가 정보를 제공합니다:

{
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": "Create job with params: {\"url\": \"https://ip.oxylabs.io\"}"
  }
}

{
  "method": "notifications/message",
  "params": {
    "level": "info",
    "data": "Job info: job_id=7333113830223918081 job_status=done"
  }
}

{
  "method": "notifications/message",
  "params": {
    "level": "error",
    "data": "Error: request to Oxylabs API failed"
  }
}

✨ 주요 기능

모든 사이트에서 콘텐츠 스크래핑

• 복잡한 단일 페이지 애플리케이션을 포함한 모든 URL에서 데이터 추출
• 헤드리스 브라우저 지원으로 동적 웹사이트 완전 렌더링
• 전체 JavaScript 렌더링, HTML 전용 또는 없음 선택
• 모바일 및 데스크톱 뷰포트 에뮬레이션으로 현실적인 렌더링

AI 준비 데이터 자동 획득

• 가독성 향상을 위해 HTML을 Markdown으로 자동 정리 및 변환
• Google, Amazon 등 인기 대상에 대한 자동 파서 사용

CAPTCHA 및 지리적 제한 관리

• 높은 성공률로 정교한 자동 요청 관리 시스템 탐색
• 가장 복잡한 웹사이트도 안정적으로 스크래핑
• 195개 이상의 국가를 포괄하는 프록시 풀에서 자동 회전 IP 획득

유연한 설정 및 크로스 플랫폼 지원

• 필요한 경우 렌더링 및 파싱 옵션 설정
• 데이터를 AI 모델 또는 분석 도구에 직접 공급
• macOS, Windows, Linux에서 작동

내장 오류 처리 및 요청 관리

• 포괄적인 오류 처리 및 보고
• 스마트 속도 제한 및 요청 관리

왜 Oxylabs MCP인가?  🕸️ ➜ 📦 ➜ 🤖

LLM에게 *"GPT‑5에 관한 최신 Hacker News 토론을 요약해줘"*라고 말하는 것을 상상해보세요 – 그러면 그냥 답변합니다. Oxylabs MCP 서버는 지루한 부분을 대신 처리하여 이를 실현합니다:

Oxylabs MCP가 하는 일	왜 중요한가
자동 요청 장벽 관리 Oxylabs 글로벌 프록시 네트워크로	웹사이트 접근 및 익명성 보장
JavaScript 렌더링 헤드리스 Chrome에서	단일 페이지 앱, 해결됨
HTML → Markdown 정리	벡터 DB 또는 프롬프트에 바로 투입
선택적 구조화 파서 (Google, Amazon 등)	인기 대상에 대한 원클릭 접근

---

🛡️ 라이선스

MIT 라이선스에 따라 배포됩니다 – 자세한 내용은 LICENSE를 참조하세요.

---

Oxylabs 소개

2015년에 설립된 Oxylabs는 시장을 선도하는 웹 인텔리전스 수집 플랫폼으로, 최고 수준의 비즈니스, 윤리 및 규정 준수 표준에 따라 전 세계 기업이 데이터 기반 인사이트를 활용할 수 있도록 지원합니다.

mcp-name: io.oxylabs/oxylabs-mcp

이 MCP를 기반으로 한 솔루션:

Michelin Detour