> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/web-scraper-api/solutions-for-ai-workflows/model-context-protocol-mcp.md).

# Model Context Protocol (MCP)

Use o Oxylabs MCP para dar a assistentes de IA ferramentas ao vivo de scraping, busca e extração web por meio da Web Scraper API e da AI Studio.

O servidor MCP da Oxylabs conecta assistentes de IA ([Claude](https://claude.ai/), [Cursor](https://www.cursor.com/), e qualquer outro [Protocolo de Contexto do Modelo](https://modelcontextprotocol.io/) cliente) à web do mundo real.

Depois de conectado, seu assistente pode extrair qualquer URL (inclui renderização de JavaScript e segmentação geográfica), pesquisar na web, rastrear sites e extrair dados estruturados.

{% hint style="success" %}
**Código-fonte aberto e registro:** Veja o código-fonte em [GitHub](https://github.com/oxylabs/oxylabs-mcp). O servidor está oficialmente registrado no [Registro MCP](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/), e [Smithery](https://smithery.ai/).
{% endhint %}

## Pré-requisitos

Você precisa de **pelo menos um** conjunto de credenciais para desbloquear suas ferramentas correspondentes. Fornecer ambos desbloqueia todas as ferramentas listadas abaixo.

<table><thead><tr><th width="287">Credenciais</th><th width="307">Onde obter</th><th width="165">Desbloqueia</th></tr></thead><tbody><tr><td>Web Scraper API <code>nome de usuário</code> &#x26; <code>senha</code></td><td><a href="https://dashboard.oxylabs.io/">painel da Oxylabs</a> (teste gratuito disponível)</td><td>ferramentas da Web Scraper API</td></tr><tr><td>chave de API do AI Studio</td><td><a href="https://aistudio.oxylabs.io/settings/api-key">Configurações do AI Studio</a> (créditos gratuitos incluídos)</td><td>ferramentas do AI Studio</td></tr></tbody></table>

{% hint style="warning" %}
Configure apenas as credenciais que você realmente tem. Valores de placeholder expõem ferramentas que falharão quando chamadas.
{% endhint %}

## Ferramentas disponíveis

<table><thead><tr><th width="204">Ferramenta</th><th width="428">O que faz</th><th width="133">Requer</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>Extrai qualquer URL. Renderização opcional de JavaScript, segmentação geográfica, saída Markdown/HTML</td><td>Web Scraper API</td></tr><tr><td><code>google_search_scraper</code></td><td>Resultados da Pesquisa Google, opcionalmente analisados em JSON estruturado</td><td>Web Scraper API</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Páginas de resultados de busca da Amazon, opcionalmente analisadas</td><td>Web Scraper API</td></tr><tr><td><code>amazon_product_scraper</code></td><td>Páginas individuais de produtos da Amazon</td><td>Web Scraper API</td></tr><tr><td><code>ai_scraper</code></td><td>Extração com IA de qualquer URL (JSON, CSV, Markdown, TOON)</td><td>AI Studio</td></tr><tr><td><code>ai_crawler</code></td><td>Rastreamento multi-página e coleta de dados guiados por prompt </td><td>AI Studio</td></tr><tr><td><code>ai_browser_agent</code></td><td>Controle de navegador guiado por prompt: navegar, clicar, preencher formulários</td><td>AI Studio</td></tr><tr><td><code>ai_search</code></td><td>Busca na web com conteúdo opcional em Markdown de cada resultado</td><td>AI Studio</td></tr><tr><td><code>ai_map</code></td><td>Mapeia URLs de sites</td><td>AI Studio</td></tr><tr><td><code>generate_schema</code></td><td>Gera esquemas personalizados de extração para as ferramentas do AI Studio</td><td>AI Studio</td></tr></tbody></table>

## Escolha como conectar

<table data-header-hidden><thead><tr><th width="117"></th><th>Hospedado (recomendado)</th><th>Local</th></tr></thead><tbody><tr><td></td><td><a href="#option-1-hosted-server-recommended"><strong>Servidor hospedado</strong></a> (recomendado)</td><td><a href="#option-2-run-the-server-locally"><strong>Servidor local</strong></a></td></tr><tr><td><strong>Instalar</strong></td><td>Nenhum</td><td><a href="https://docs.astral.sh/uv/">uv</a> + <code>uvx oxylabs-mcp</code></td></tr><tr><td><strong>Endpoint</strong></td><td><code>https://mcp.oxylabs.io/mcp</code></td><td>Cursor/Claude iniciam o processo</td></tr><tr><td><strong>Credenciais</strong></td><td>Cabeçalhos HTTP</td><td>Variáveis de ambiente</td></tr><tr><td><strong>Melhor para</strong></td><td>Configuração mais rápida, sem gerenciamento</td><td>Controle offline, depuração local, clientes que não podem enviar cabeçalhos personalizados</td></tr></tbody></table>

## Método 1: Servidor hospedado (recomendado)

Conecte-se ao servidor MCP hospedado da Oxylabs:

```
https://mcp.oxylabs.io/mcp
```

Passe as credenciais como cabeçalhos da solicitação:

<table><thead><tr><th width="240">Credencial</th><th>Cabeçalho</th></tr></thead><tbody><tr><td>Web Scraper API</td><td><code>Authorization: Basic &#x3C;base64(username:password)></code></td></tr><tr><td>AI Studio</td><td><code>X-Oxylabs-AI-Studio-Api-Key: &#x3C;your API key></code></td></tr></tbody></table>

{% hint style="warning" %}
**Observação:** Inclua apenas os cabeçalhos das credenciais que você tem.
{% endhint %}

### Claude Code

Instale diretamente na linha de comando:

```bash
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"
```

Omita uma `--header` linha se você não tiver essa credencial.

### Claude Desktop

O editor de configuração integrado do Claude Desktop usa servidores locais (`comando`) servidores. Para o endpoint hospedado, use o Claude Code com o comando HTTP acima, ou [execute o servidor localmente](#claude-desktop-2) e aponte o Claude Desktop para essa configuração.

### Cursor

1. Abra **Configurações do Cursor** → **Personalizar** na barra lateral → **MCPs**
2. Clique **+ Novo**
3. Escolha **Usuário** (todos os projetos) ou **Projeto** (apenas o espaço de trabalho)
4. Adicione o seguinte ao `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "url": "https://mcp.oxylabs.io/mcp",
         "headers": {
           "Authorization": "Basic <base64 of username:password>",
           "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Salve e, em seguida, confirme se o servidor está ativado em **Personalizar → MCPs**.

{% hint style="info" %}
**Observação:** *Usuário* grava em `~/.cursor/mcp.json`. *Espaço de trabalho* grava em `.cursor/mcp.json` no espaço de trabalho escolhido. Se ambos definirem o mesmo nome de servidor, a *configuração do espaço de trabalho* tem prioridade.
{% endhint %}

## Método 2: Servidor local

O servidor está disponível em nosso [repositório PyPI](https://pypi.org/project/oxylabs-mcp/).&#x20;

Se ainda não estiver instalado, instale o [pacote uv](https://docs.astral.sh/uv/) de acordo com o sistema operacional escolhido:

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}
{% endtabs %}

As credenciais são passadas como variáveis de ambiente (defina **apenas** as que você tiver):

| Variável                    | Descrição                          |
| --------------------------- | ---------------------------------- |
| `OXYLABS_USERNAME`          | nome de usuário da Web Scraper API |
| `OXYLABS_PASSWORD`          | senha da Web Scraper API           |
| `OXYLABS_AI_STUDIO_API_KEY` | chave de API do AI Studio          |

### Claude Code

```bash
claude mcp add oxylabs -- command uvx args oxylabs-mcp \
  --env OXYLABS_USERNAME=YOUR_USERNAME \
  --env OXYLABS_PASSWORD=YOUR_PASSWORD \
  --env OXYLABS_AI_STUDIO_API_KEY=YOUR_API_KEY
```

{% hint style="info" %}
Caminho de configuração manual para o Claude Code: `~/.config/claude/mcp.json` (macOS/Linux) ou `%USERPROFILE%\.config\claude\mcp.json` (Windows). A estrutura JSON corresponde ao Claude Desktop.
{% endhint %}

### Claude Desktop

1. Abra **Claude → Configurações → Desenvolvedor → Editar Configuração**
2. Adicione o seguinte a `claude_desktop_config.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
3. Reinicie o Claude Desktop

### Cursor

1. Abra **Configurações do Cursor** → **Personalizar** na barra lateral → **MCPs**
2. Clique **+ Novo**
3. Escolha **Usuário** (todos os projetos) ou **Projeto** (apenas o espaço de trabalho)
4. Adicione o seguinte ao `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Salve e, em seguida, confirme se o servidor está ativado em **Personalizar → MCPs**.

{% hint style="info" %}
**Observação:** *Usuário* grava em `~/.cursor/mcp.json`. *Espaços de trabalho* grava em `.cursor/mcp.json` no espaço de trabalho escolhido. Se ambos definirem o mesmo nome de servidor, a *configuração do espaço de trabalho* tem prioridade.
{% endhint %}

## Verifique a configuração

Depois de conectar, peça ao seu assistente algo que exija dados da web em tempo real (por exemplo, `“Raspe https://ip.oxylabs.io e retorne o conteúdo como Markdown.”`):

{% stepper %}
{% step %}
Confirme se o `oxylabs` servidor aparece e está ativado na lista MCP do seu cliente.
{% endstep %}

{% step %}
Aprove a chamada da ferramenta quando solicitado (os clientes pedem antes de executar ferramentas MCP por padrão).
{% endstep %}

{% step %}
Se a chamada falhar, verifique as credenciais e os logs do cliente (Cursor: **Saída → Logs do MCP**).
{% endstep %}
{% endstepper %}

## Solução de problemas

<table><thead><tr><th width="251">Erro</th><th>Solução</th></tr></thead><tbody><tr><td>Servidor ausente no cliente</td><td>Reinicie o app após editar a configuração. Confirme se o JSON é válido.</td></tr><tr><td>Ferramentas listadas, mas as chamadas falham</td><td>Credenciais de placeholder, Base64 incorreto ou cabeçalho/variável de ambiente ausente para essa ferramenta.</td></tr><tr><td>A URL hospedada não conecta</td><td>O cliente pode não suportar cabeçalhos personalizados; use a configuração local.</td></tr><tr><td><code>uvx</code> / comando não encontrado</td><td>Instalar <a href="https://docs.astral.sh/uv/">uv</a> e garanta que ele esteja no seu <code>PATH</code>.</td></tr><tr><td>O caminho da interface do Cursor parece diferente</td><td>Ignore a interface e edite <code>mcp.json</code> diretamente (os rótulos podem mudar entre as versões do Cursor).</td></tr></tbody></table>

{% hint style="success" %}
Para problemas ou solicitações de funcionalidades, abra um issue no GitHub ou entre em contato com o suporte 24/7 da Oxylabs em [**support@oxylabs.io**](mailto:support@oxylabs.io).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/solutions-for-ai-workflows/model-context-protocol-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.