Overview

The Oxylabs MCP Server implements the Model Context Protocol (MCP) as a lightweight backend that exposes web-scraping and location-aware tooling to language models and other agent frameworks. By running this server alongside an LLM agent, developers can invoke real-world web actions (fetch pages, extract structured content, take screenshots, run localized searches) in a standardized, tool-like way the model can reason about and call.

This server is useful when you need deterministic, auditable web access for AI workflows: it isolates scraping logic from the model, centralizes proxy and rate-limit configuration, and returns structured results with metadata (status, headers, timestamps). It can be deployed locally, in containers, or alongside Oxylabs infrastructure to leverage proxy networks and extraction services.

Features

Implements MCP-style tool discovery and execution for web scraping tasks
Exposes multiple web-oriented tools: page fetch, structured extraction, screenshots, localized search
Configurable proxy and credentials for Oxylabs services
Runs in Docker or as a local process for easy development
Returns structured outputs with metadata for reliable downstream usage
Health and metrics endpoints suitable for orchestration and monitoring

Installation / Configuration

Clone the repository and run with Docker (recommended):

git clone https://github.com/oxylabs/oxylabs-mcp.git
cd oxylabs-mcp

# Build and run with Docker
docker build -t oxylabs-mcp .
docker run -p 8080:8080 \
  -e OXYLABS_API_KEY="${OXYLABS_API_KEY}" \
  -e MCP_PORT=8080 \
  -e LOG_LEVEL=info \
  oxylabs-mcp

Example Docker Compose snippet:

version: "3.8"
services:
  mcp-server:
    image: oxylabs-mcp:latest
    build: .
    ports:
      - "8080:8080"
    environment:
      OXYLABS_API_KEY: ${OXYLABS_API_KEY}
      MCP_PORT: 8080
      LOG_LEVEL: info
    restart: unless-stopped

Minimal .env example (place at project root or inject into container):

# .env
OXYLABS_API_KEY=your_api_key_here
MCP_PORT=8080
LOG_LEVEL=info
PROXY_URL=http://username:[email protected]:12345
ALLOWED_HOSTS=example.com,example.org

Common environment variables

Variable	Purpose	Default
OXYLABS_API_KEY	API key to authenticate with Oxylabs services	(required)
MCP_PORT	Port where the MCP server listens	8080
PROXY_URL	Optional upstream proxy for requests	(none)
LOG_LEVEL	Logging verbosity (debug/info/warn/error)	info
ALLOWED_HOSTS	Comma-separated host allowlist	(none)

Available Resources

The server exposes discoverable tools/resources that an agent can enumerate and call. Typical resources include:

scrape/page — fetch an HTML page with headers and status
extract — run an extraction spec (CSS/XPath/jsonpath) and return structured data
screenshot — capture a rendered screenshot (PNG or JPEG) of a URL
search/local — perform location-aware queries and return results (titles, snippets, URLs)
health/metrics — operational endpoints for readiness and telemetry

Each resource returns a consistent response shape: status metadata (HTTP status, request id, timing), raw content (HTML, image blob, JSON), and optional structured extraction results.

Example: list available tools

curl http://localhost:8080/mcp/tools
# returns JSON array with tool name, description, inputs schema

Example: call a tool (scrape)

curl -X POST http://localhost:8080/mcp/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "scrape/page",
    "input": {
      "url": "https://example.com",
      "render": false,
      "headers": {"User-Agent": "mcp-client/1.0"}
    }
  }'

Use Cases

Augment an LLM with browsing for up-to-date facts: the model can request a scrape of a news page or documentation URL and get back HTML plus a short extracted summary for citation.
Price or availability monitoring: schedule the MCP server to fetch product pages and extract structured price and stock fields; store results and feed diffs into an alerting pipeline.
Localized search and testing: use the search/local tool to simulate searches from different geographic contexts (via configured proxies) so an LLM can reason about region-specific results.
Screenshot-based QA: capture rendered pages for visual verification in workflows that need to compare layout or appearance across versions or locales.
Data extraction pipeline: use extract tools to convert HTML pages into JSON records for downstream ingestion; MCP centralizes extraction logic and proxies so models don’t directly access the public web.

Getting Started Tips

Secure the endpoint: restrict access to the MCP server behind network controls or authentication to avoid arbitrary third-party scraping from your deployment.
Use allowlists: set ALLOWED_HOSTS to limit which domains can be scraped.
Monitor rate limits and costs: if connected to Oxylabs scraping services or

Oxylabs MCP Server: AI-Ready Web Scraping