Oxylabs

Oxylabs MCP Server

AI 모델과 실제 웹 사이의 빠진 연결 고리: 어떤 사이트에서든 깔끔하고 구조화된 데이터를 제공하는 단 하나의 API.

---

면책 조항

이 저장소는 계속해서 완전히 지원됩니다. 하지만 Oxylabs Web API를 사용 중이라면 Web API MCP 저장소를 참조하세요. Web API MCP

📖 개요

Oxylabs MCP 서버는 AI 모델과 웹을 연결합니다. 이를 통해 모든 URL을 스크래핑하고, JavaScript가 많은 페이지를 렌더링하며, AI에서 사용할 콘텐츠를 추출하고 형식을 지정하고, CAPTCHA를 처리하고, 195개 이상의 국가에서 지역 제한이 있는 웹 데이터에 액세스할 수 있습니다.

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

mcp-name: io.oxylabs/oxylabs-mcp

🛠️ MCP 도구

Oxylabs MCP는 함께 또는 독립적으로 사용할 수 있는 두 가지 도구 모음을 제공합니다.

Oxylabs Web Scraper API 도구

1. universal_scraper: 선택적 JavaScript 렌더링, 지역 타겟팅, Markdown/HTML/링크 출력 기능으로 모든 URL을 스크래핑합니다.
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 대시보드에서 API 토큰(또는 사용자 이름과 비밀번호)을 발급받으세요(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: Bearer <token>
Web Scraper API 토큰(대체)	X-Oxylabs-Api-Token
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

API 토큰과 사용자 이름 및 비밀번호를 모두 전달하면 토큰이 사용됩니다.

Claude Code 설정:

claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"

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

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://mcp.oxylabs.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

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

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

옵션 2: 로컬에서 실행

환경 변수

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

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

Web Scraper API 도구를 사용하려면 OXYLABS_API_TOKEN 또는 OXYLABS_USERNAME와 OXYLABS_PASSWORD을 모두 설정하세요. 둘 다 설정하면 토큰이 사용됩니다. AI Studio 도구를 사용하려면 OXYLABS_AI_STUDIO_API_KEY을 설정하세요.

모든 도구는 항상 목록에 표시됩니다. 필요한 자격 증명 없이 도구를 호출하면 무엇을 설정해야 하는지 설명하는 오류 메시지가 반환됩니다.

❗ 중요: 실제 자격 증명이 있는 환경 변수만 설정하세요. 자리 표시자 값으로는 도구 호출이 실패합니다.

uvx로 구성

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

{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_API_TOKEN": "YOUR_API_TOKEN",
        "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_API_TOKEN": "YOUR_API_TOKEN",
        "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

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

서버는 MCP streamable-HTTP 전송도 지원합니다. 다음 명령으로 시작하세요.

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

HTTP 전송에서는 환경 변수 대신 요청별로 자격 증명을 전달합니다.

자격 증명	전달 방법
Web Scraper API 토큰(권장)	Authorization: Bearer <token>
Web Scraper API 토큰(대체)	X-Oxylabs-Api-Token 헤더
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": "Bearer YOUR_API_TOKEN",
        "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

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

Claude Desktop 설정

Claude → Settings → Developer → Edit Config로 이동한 다음 위 구성 중 하나를 claude_desktop_config.json 파일에 추가하세요.

Cursor AI 설정

Cursor → Settings → Cursor Settings → MCP로 이동하세요. Add new global MCP server를 클릭하고 위 구성 중 하나를 추가하세요.

📝 로깅

서버는 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 글로벌 프록시 네트워크로 자동화된 요청 차단을 처리합니다.	웹사이트에 액세스하고 익명성을 유지할 수 있습니다.
헤드리스 Chrome에서 JavaScript를 렌더링합니다.	단일 페이지 앱도 문제없습니다.
HTML을 정리해 Markdown으로 변환합니다.	벡터 DB나 프롬프트에 바로 넣을 수 있습니다.
선택적 구조화 파서(Google, Amazon 등)를 제공합니다.	인기 대상에 한 줄로 액세스할 수 있습니다.

---

🛡️ 라이선스

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

---

Oxylabs 소개

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

이 MCP를 기반으로 만든 솔루션:

Michelin Detour