Oxylabs

Сервер Oxylabs MCP

Недостающее звено между моделями ИИ и реальным вебом: единый API, который предоставляет чистые структурированные данные с любого сайта.

---

Отказ от ответственности

Этот репозиторий по-прежнему полностью поддерживается, но если вы используете Oxylabs Web API, обратитесь к репозиторию Web API MCP: Web API MCP

📖 Обзор

Сервер Oxylabs MCP служит связующим звеном между моделями ИИ и вебом. Он позволяет собирать данные с любых URL, отображать страницы с большим количеством JavaScript, извлекать и форматировать контент для использования ИИ, обходить CAPTCHA и получать доступ к географически ограниченным веб-данным из более чем 195 стран.

Он построен на основе Model Context Protocol (MCP) — открытого стандарта для подключения ИИ-ассистентов к внешним инструментам и данным.

mcp-name: io.oxylabs/oxylabs-mcp

🛠️ Инструменты MCP

Oxylabs MCP предоставляет два набора инструментов, которые можно использовать вместе или по отдельности:

Инструменты Oxylabs Web Scraper API

1. universal_scraper: собирает данные с любого URL, с возможностью включить рендеринг JavaScript, геотаргетинг и вывод в формате Markdown/HTML/ссылок;
2. google_search_scraper: извлекает результаты Google Search, с возможностью преобразовать их в структурированный JSON;
3. amazon_search_scraper: собирает данные со страниц результатов поиска Amazon, с возможностью преобразовать их в структурированный JSON;
4. amazon_product_scraper: извлекает данные с отдельных страниц товаров Amazon.

Инструменты Oxylabs AI Studio

5. ai_scraper: собирает контент с любого URL с помощью извлечения на основе ИИ в форматах JSON, CSV, Markdown или TOON;
6. ai_crawler: обходит сайт, начиная с указанного URL, на основе запроса и собирает данные с нескольких страниц;
7. ai_browser_agent: управляет настоящим браузером на основе запроса — переходит по страницам, нажимает кнопки, заполняет формы — и возвращает результат;
8. ai_search: ищет в интернете и при необходимости возвращает содержимое каждой страницы результата в формате Markdown;
9. ai_map: составляет карту URL сайта с фильтрацией по ключевым словам или запросу;
10. generate_schema: генерирует схему JSON в формате OpenAPI для структурированного извлечения с помощью перечисленных выше инструментов ИИ.

✅ Предварительные требования

Перед началом убедитесь, что у вас есть как минимум одно из следующего:

• Учётная запись Oxylabs Web Scraper API: получите API-токен (или имя пользователя и пароль) в панели управления Oxylabs (доступна бесплатная пробная версия на 1 неделю);
• Ключ API Oxylabs AI Studio: получите ключ API в Oxylabs AI Studio (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), пока не могут передавать заголовки — поддержка входа через 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	Ваш ключ API Oxylabs AI Studio
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 auth)
Имя пользователя и пароль 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 или отключение рендеринга
• Эмуляция мобильных и настольных экранов для реалистичного отображения

Автоматическое получение данных, готовых для ИИ

• Автоматическая очистка и преобразование HTML в Markdown для повышения удобочитаемости
• Использование автоматических парсеров для популярных ресурсов, таких как Google, Amazon и других

Обход CAPTCHA и географических ограничений

• Обход сложных систем управления автоматизированными запросами с высокой вероятностью успеха
• Надёжный сбор данных даже с самых сложных сайтов
• Автоматическая ротация IP-адресов из пула прокси, охватывающего более 195 стран

Гибкая настройка и поддержка разных платформ

• При необходимости задавайте параметры рендеринга и парсинга
• Передавайте данные напрямую в модели ИИ или инструменты аналитики
• Работает в macOS, Windows и Linux

Встроенная обработка ошибок и управление запросами

• Комплексная обработка ошибок и создание отчётов
• Интеллектуальное ограничение частоты запросов и управление ими

Почему Oxylabs MCP?  🕸️ ➜ 📦 ➜ 🤖

Представьте, что вы говорите своей LLM: «Кратко перескажи последнее обсуждение GPT‑5 на Hacker News» — и она просто отвечает. Сервер Oxylabs MCP делает это возможным, беря на себя всю рутинную работу:

Что делает Oxylabs MCP	Чем это полезно
Обходит блокировки автоматизированных запросов с помощью глобальной сети прокси Oxylabs	Обеспечивает доступ к сайтам и анонимность
Рендерит JavaScript в безголовом Chrome	Одностраничные приложения — без проблем
Очищает HTML → Markdown	Данные можно сразу передавать в векторные БД или промпты
Необязательные структурированные парсеры (Google, Amazon и др.)	Доступ к популярным ресурсам одной строкой

---

🛡️ Лицензия

Распространяется по лицензии MIT — подробности см. в файле LICENSE.

---

Об Oxylabs

Основанная в 2015 году, компания Oxylabs — ведущая платформа для сбора веб-данных, работающая в соответствии с высочайшими стандартами деловой этики и соблюдения нормативных требований и помогающая компаниям по всему миру получать аналитические выводы на основе данных.

Решения, созданные на основе этого MCP:

Michelin Detour