Oxylabs

Oxylabs MCP Server

O elo que faltava entre modelos de IA e a web do mundo real: uma 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 que eles façam scraping de qualquer URL, renderizem páginas com muito JavaScript, extraiam e formatem conteúdo para uso em IA, gerenciem CAPTCHA e acessem dados 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 de forma independente:

Ferramentas da Oxylabs Web Scraper API

1. universal_scraper: faz scraping de 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 parsing opcional em JSON estruturado;
3. amazon_search_scraper: faz scraping de páginas de resultados de busca da Amazon, com parsing 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: faz scraping de conteúdo de qualquer URL com extração alimentada por IA, em formato 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 schema 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 na Oxylabs Web Scraper API: obtenha seu nome de usuário e senha em Oxylabs (teste gratuito de 1 semana disponível);
• Chave da API do Oxylabs AI Studio: obtenha sua chave de API em Oxylabs AI Studio (1000 créditos grátis).

Para executar o servidor localmente (Opção 2 abaixo), você também precisará do gerenciador de pacotes 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"

📦 Configuração

Há duas maneiras de usar o servidor: conectar-se à instância hospedada (sem instalação) ou executá-lo localmente com credenciais em variáveis de ambiente.

Opção 1: Servidor hospedado (sem instalação)

A Oxylabs executa um servidor MCP hospedado em:

https://mcp.oxylabs.io/mcp

As credenciais são passadas com cabeçalhos de solicitação:

Credencial	Cabeçalho
Web Scraper API	Authorization: Basic <base64(username:password)>
Web Scraper API (alternativa)	X-Oxylabs-Username e X-Oxylabs-Password
AI Studio	X-Oxylabs-AI-Studio-Api-Key

Configuração com 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"

Configuração com Cursor ou qualquer cliente que suporte servidores MCP remotos com cabeçalhos personalizados:

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

O servidor também está listado no Smithery.

Nota: clientes que suportam apenas OAuth para servidores remotos (por exemplo, adicionar um conector personalizado na interface web do claude.ai) ainda não podem passar cabeçalhos — o login via OAuth está no nosso roadmap. Use a configuração local abaixo com esses clientes enquanto isso.

Opção 2: Executar localmente

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 do Oxylabs AI Studio
LOG_LEVEL	Nível de log para os logs 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 fornecidos, o servidor expõe as ferramentas da Web Scraper API;
• Se apenas OXYLABS_AI_STUDIO_API_KEY for fornecido, o servidor expõe as ferramentas do AI Studio;
• Se todos os três forem fornecidos, 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"
      }
    }
  }
}

Executando como um servidor HTTP remoto (auto-hospedado)

O servidor também suporta o transporte MCP streamable-HTTP. Inicie-o 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 solicitação em vez de variáveis de ambiente:

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

Exemplo de configuração do 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 → Configurações → Desenvolvedor → Editar Config e adicione uma das configurações acima ao arquivo claude_desktop_config.json.

Configuração com Cursor AI

Navegue até Cursor → Configurações → Configurações do Cursor → MCP. Clique em Adicionar novo servidor MCP global e adicione uma das configurações acima.

📝 Registro de Logs

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

Faça scraping de conteúdo de qualquer site

• Extraia dados de qualquer URL, incluindo aplicativos complexos de página única
• Renderize totalmente sites dinâmicos usando suporte a navegador headless
• Escolha renderização completa de JavaScript, apenas HTML ou nenhuma
• Emule viewports de dispositivos móveis e desktop para renderização realista

Obtenha automaticamente dados prontos para IA

• Limpe e converta automaticamente HTML para Markdown para melhor legibilidade
• Use parsers automatizados para alvos populares como Google, Amazon e outros

Gerencie CAPTCHA e restrições geográficas

• Navegue por sistemas sofisticados de gerenciamento automatizado de solicitações com alta taxa de sucesso
• Faça scraping confiável até dos 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 parsing 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 solicitações integrados

• Tratamento e relatório abrangentes de erros
• Limitação de taxa inteligente e gerenciamento de solicitaçõ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 chatas para você:

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

---

🛡️ Licença

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

---

Sobre a Oxylabs

Estabelecida 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

Soluções feitas com base neste MCP:

Michelin Detour