Skip to directory

Oxylabs Web API MCP

Oxylabs

Transport not documented6 documented tools9

About Oxylabs Web API MCP

A self-hosted MCP server that exposes Oxylabs Web API live search, page scraping, scraper discovery, structured extraction, and large-result retrieval to MCP clients.

What you can use it for

  • Search the live web for sources
  • Read and extract a specific page as Markdown, HTML, JSON, or screenshot
  • Use target-specific structured scrapers
  • Retrieve asynchronous scrape results or large page content
Connection and setup
Hosting
local stdio or self-hosted HTTP/Docker
Transport
Not documented
Endpoint
Local process; no hosted endpoint documented
Authentication
Requires an Oxylabs Web API product instance and API key. For stdio, set OXYLABS_WEB_API_KEY locally; for HTTP, send a per-request Authorization: Bearer key or configure a server-side fallback. The HTTP server does not provide its own authentication; do not expose it publicly without an authenticated private gateway.

Requirements

  • Python 3.10+
  • uv or pipx for isolated install, or Docker
  • Oxylabs account with Web API product instance and API key

Setup steps

  1. Create an Oxylabs Dashboard account and a Web API product instance, then generate its API key. Web API usage is billed per successful request; the first-account welcome credit is subject to current offer and should not be assumed.
  2. Install using uv tool install git+https://github.com/oxylabs/web-api-mcp. The project also documents pipx install git+https://github.com/oxylabs/web-api-mcp.
  3. Configure the client to start oxylabs-web-api-mcp over stdio and set OXYLABS_WEB_API_KEY in the local process environment.
  4. Reload the client and make a low-cost read-only search request. Use scrape for page content; enable JavaScript rendering only when the unrendered page is empty or thin, as rendering is slower and billed.
  5. For team HTTP/Docker hosting, configure OXYLABS_WEB_API_KEY, MCP_ALLOWED_HOSTS, and access controls before serving; the README explicitly warns the server has no built-in HTTP authentication.
Tools 6

Official repository documents six exact tools. Requires a paid Oxylabs Web API account/key; new accounts may receive a $5 trial credit, then successful search/scrape requests are billed. Self-hosted HTTP mode has no built-in authentication; keep it behind a private authenticated gateway.

  • search

    Search the live web and return ranked organic results (title, description, URL).

    01
  • scrape

    Read one URL, Markdown by default; can return screenshot or structured JSON and render JavaScript pages.

    02
  • check_scrape

    Collect the result of a scrape running in the background.

    03
  • read_scraped

    Read large page content from the local spill file in chunks.

    04
  • list_scrapers

    List available scrape endpoints or describe endpoint parameters.

    05
  • scrape_target

    Call a target-specific scraper and return content or structured JSON.

    06
Limitations and notes
  • Web API requires an account/API key and usage is charged per successful request; AI parsing and some output modes can incur extra credit cost.
  • JavaScript rendering is slower and billable; use it only for thin or JavaScript-dependent pages.
  • HTTP deployment has no built-in authentication; a reachable endpoint can consume the configured key. Protect behind VPN/authenticated gateway and set MCP_ALLOWED_HOSTS.
  • scrape accepts caller-provided URLs; apply network egress controls if serving untrusted prompts.
  • Older repository oxylabs/oxylabs-mcp is archived and is not this current implementation.
Source discrepancies
  • The older GitHub repository oxylabs/oxylabs-mcp was archived on 2026-09-16; the newer oxylabs/web-api-mcp is a separately named current implementation documented by Oxylabs. The older repository is not silently reused for current setup.
Original sources
  • official publisher documentation

    Oxylabs agent docs specify Web API search/scrape endpoints, Bearer-key auth, request parameters, response shapes, and retry rules. These describe the underlying Web API used by MCP tools.

  • official tool reference

    Current official repo lists six exact tools, local/self-hosted transports, bearer-key configuration, host allow-list and spend/rate controls.

  • official product documentation

    Current official quickstart explains account/API key setup, MCP install, $5 welcome credit, and successful-request billing.

Documentation checked 2026-10-28. Connection has not been runtime tested.

Similar tools