Oxylabs

Oxylabs MCP Server

O elo que faltava entre modelos de IA e a web do mundo real: uma única API que entrega dados limpos e estruturados de qualquer site.

---

📖 Visão Geral

O servidor Oxylabs MCP fornece uma ponte entre modelos de IA e a web. Ele permite extrair qualquer URL, renderizar páginas com muito JavaScript, extrair e formatar conteúdo para uso em IA, gerenciar CAPTCHA e acessar dados da web com restrição geográfica de mais de 195 países.

Ele é construído sobre o Model Context Protocol (MCP), o padrão aberto para conectar assistentes de IA a ferramentas e dados externos.

🛠️ Ferramentas MCP

O Oxylabs MCP fornece dois conjuntos de ferramentas que podem ser usados juntos ou independentemente:

Ferramentas da Oxylabs Web Scraper API

1. universal_scraper: extrai qualquer URL, com renderização opcional de JavaScript, segmentação geográfica e saída em Markdown/HTML/links;
2. google_search_scraper: extrai resultados do Google Search, com análise opcional em JSON estruturado;
3. amazon_search_scraper: extrai páginas de resultados de busca da Amazon, com análise opcional em JSON estruturado;
4. amazon_product_scraper: extrai dados de páginas individuais de produtos da Amazon.

Ferramentas do Oxylabs AI Studio

5. ai_scraper: extrai conteúdo de qualquer URL com extração alimentada por IA, nos formatos JSON, CSV, Markdown ou TOON;
6. ai_crawler: rastreia um site a partir de uma URL inicial com base em um prompt e coleta dados em várias páginas;
7. ai_browser_agent: controla um navegador real com base em um prompt — navega, clica, preenche formulários — e retorna o resultado;
8. ai_search: pesquisa na web e opcionalmente retorna o conteúdo em Markdown de cada resultado;
9. ai_map: mapeia as URLs de um site, filtradas por palavras-chave ou um prompt;
10. generate_schema: gera um esquema JSON no formato OpenAPI para extração estruturada com as ferramentas de IA acima.

✅ Pré-requisitos

Antes de começar, certifique-se de ter pelo menos um dos seguintes:

• Conta Oxylabs Web Scraper API: obtenha seu nome de usuário e senha na Oxylabs (teste gratuito de 1 semana disponível);
• Chave da API Oxylabs AI Studio: obtenha sua chave de API no Oxylabs AI Studio (1000 créditos grátis).

Você também precisará do gerenciador de pacotes uv para executar o servidor:

# 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"

📦 Configuração

Variáveis de ambiente

O servidor Oxylabs MCP suporta as seguintes variáveis de ambiente:

Nome	Descrição	Padrão
OXYLABS_USERNAME	Seu nome de usuário da Oxylabs Web Scraper API
OXYLABS_PASSWORD	Sua senha da Oxylabs Web Scraper API
OXYLABS_AI_STUDIO_API_KEY	Sua chave da API Oxylabs AI Studio
LOG_LEVEL	Nível de log para os registros retornados ao cliente	INFO

Com base nas credenciais fornecidas, o servidor expõe automaticamente as ferramentas correspondentes:

• Se apenas OXYLABS_USERNAME e OXYLABS_PASSWORD forem fornecidas, o servidor expõe as ferramentas da Web Scraper API;
• Se apenas OXYLABS_AI_STUDIO_API_KEY for fornecida, o servidor expõe as ferramentas do AI Studio;
• Se todas as três forem fornecidas, o servidor expõe todas as ferramentas.

❗ Importante: defina apenas as variáveis de ambiente para as quais você tem credenciais reais. Deixar valores de espaço reservado resultará em ferramentas expostas que não funcionam.

Configurar com uvx

Instala o pacote do PyPI e o executa automaticamente:

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

Configurar com um checkout local

Útil para desenvolvimento — executa o servidor a partir de um clone local deste repositório:

{
  "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"
      }
    }
  }
}

Executar como servidor HTTP remoto (self-hosting)

O servidor também suporta o transporte streamable-HTTP do MCP. Inicie com:

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

Com o transporte HTTP, as credenciais são passadas por requisição em vez de variáveis de ambiente:

Credencial	Como passar
Web Scraper API	Authorization: Basic <base64(username:password)> (autenticação HTTP Basic padrão)
Web Scraper API (alternativa)	X-Oxylabs-Username e cabeçalhos X-Oxylabs-Password
AI Studio	cabeçalho X-Oxylabs-AI-Studio-Api-Key

Exemplo de configuração de cliente:

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

Todas as ferramentas são sempre listadas independentemente das credenciais fornecidas; chamar uma ferramenta sem as credenciais necessárias retorna uma mensagem de erro explicando exatamente o que configurar.

Configuração com Claude Desktop

Navegue até Claude → Settings → Developer → Edit Config e adicione uma das configurações acima ao arquivo claude_desktop_config.json.

Configuração com Cursor AI

Navegue até Cursor → Settings → Cursor Settings → MCP. Clique em Add new global MCP server e adicione uma das configurações acima.

📝 Registros (Logging)

O servidor fornece informações adicionais sobre as chamadas de ferramentas nos eventos 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"
  }
}

✨ Principais Recursos

Extraia conteúdo de qualquer site

• Extraia dados de qualquer URL, incluindo aplicações complexas de página única
• Renderize completamente sites dinâmicos usando suporte a navegador headless
• Escolha renderização completa de JavaScript, somente HTML ou nenhuma
• Emule viewports de Mobile e Desktop para renderização realista

Obtenha automaticamente dados prontos para IA

• Limpe e converta automaticamente HTML para Markdown para melhor legibilidade
• Use analisadores automáticos para alvos populares como Google, Amazon e outros

Gerencie CAPTCHA e restrições geográficas

• Navegue por sistemas sofisticados de gerenciamento automatizado de requisições com alta taxa de sucesso
• Extraia de forma confiável até os sites mais complexos
• Obtenha IPs rotativos automaticamente de um pool de proxies que cobre mais de 195 países

Configuração flexível e suporte multiplataforma

• Defina opções de renderização e análise se necessário
• Alimente dados diretamente em modelos de IA ou ferramentas de análise
• Funciona em macOS, Windows e Linux

Tratamento de erros e gerenciamento de requisições integrados

• Tratamento e relatório de erros abrangentes
• Limitação de taxa inteligente e gerenciamento de requisições

Por que Oxylabs MCP?  🕸️ ➜ 📦 ➜ 🤖

Imagine dizer ao seu LLM "Resuma a discussão mais recente do Hacker News sobre GPT‑5" – e ele simplesmente responde. O servidor Oxylabs MCP torna isso possível fazendo as partes tediosas por você:

O que o Oxylabs MCP faz	Por que isso importa para você
Gerencia paredes de requisições automatizadas com a rede global de proxies da Oxylabs	Permite acesso a sites e anonimato
Renderiza JavaScript no Chrome headless	Aplicações de página única, resolvidas
Limpa HTML → Markdown	Insira diretamente em DBs vetoriais ou prompts
Analisadores estruturados opcionais (Google, Amazon, etc.)	Acesso em uma linha a alvos populares

---

🛡️ Licença

Distribuído sob a Licença MIT – veja LICENSE para detalhes.

---

Sobre a Oxylabs

Fundada em 2015, a Oxylabs é uma plataforma líder de mercado em coleta de inteligência web, movida pelos mais altos padrões de negócios, ética e conformidade, permitindo que empresas em todo o mundo desbloqueiem insights orientados por dados.

mcp-name: io.oxylabs/oxylabs-mcp