\n The missing link between AI models and the real‑world web: one API that delivers clean, structured data from any site.\n
\n\n
\n\n[](https://pypi.org/project/oxylabs-mcp/)\n[](https://discord.gg/Pds3gBmKMH)\n[](LICENSE)\n[](https://mseep.ai/app/f6a9c0bc-83a6-4f78-89d9-f2cec4ece98d)\n\n\n \n\n \n\n\n
\n\n---\n\n## 📖 Overview\n\nThe Oxylabs MCP server provides a bridge between AI models and the web. It enables them to scrape any URL, render JavaScript-heavy pages, extract and format content for AI use, manage CAPTCHA, and access geo-restricted web data from 195+ countries.\n\nIt is built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), the open standard for connecting AI assistants to external tools and data.\n\n\n## 🛠️ MCP Tools\n\nOxylabs MCP provides two sets of tools that can be used together or independently:\n\n### Oxylabs Web Scraper API tools\n\n1. **universal_scraper**: scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output;\n2. **google_search_scraper**: extracts results from Google Search, with optional parsing into structured JSON;\n3. **amazon_search_scraper**: scrapes Amazon search result pages, with optional parsing into structured JSON;\n4. **amazon_product_scraper**: extracts data from individual Amazon product pages.\n\n### Oxylabs AI Studio tools\n\n5. **ai_scraper**: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;\n6. **ai_crawler**: crawls a website from a starting URL based on a prompt and collects data across multiple pages;\n7. **ai_browser_agent**: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;\n8. **ai_search**: searches the web and optionally returns Markdown content of each result;\n9. **ai_map**: maps a website's URLs, filtered by keywords or a prompt;\n10. **generate_schema**: generates an OpenAPI-format JSON schema for structured extraction with the AI tools above.\n\n\n## ✅ Prerequisites\n\nBefore you begin, make sure you have **at least one** of the following:\n\n- **Oxylabs Web Scraper API account**: obtain your username and password from [Oxylabs](https://dashboard.oxylabs.io/) (1-week free trial available);\n- **Oxylabs AI Studio API key**: obtain your API key from [Oxylabs AI Studio](https://aistudio.oxylabs.io/settings/api-key) (1000 credits free).\n\nTo run the server locally (Option 2 below) you will also need the [uv](https://docs.astral.sh/uv/) package manager:\n\n```bash\n# macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n```powershell\n# Windows\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n## 📦 Configuration\n\nThere are two ways to use the server: connect to the **hosted instance** (no installation)\nor **run it locally** with credentials in environment variables.\n\n### Option 1: Hosted server (no installation)\n\nOxylabs runs a hosted MCP server at:\n\n```\nhttps://mcp.oxylabs.io/mcp\n```\n\nCredentials are passed with request headers:\n\n| Credential | Header |\n|--------------------------------|------------------------------------------------------------------|\n| Web Scraper API | `Authorization: Basic ` |\n| Web Scraper API (alternative) | `X-Oxylabs-Username` and `X-Oxylabs-Password` |\n| AI Studio | `X-Oxylabs-AI-Studio-Api-Key` |\n\nSetup with **Claude Code**:\n\n```bash\nclaude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \\\n --header \"Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)\" \\\n --header \"X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY\"\n```\n\nSetup with **Cursor** or any client that supports remote MCP servers with custom headers:\n\n```json\n{\n \"mcpServers\": {\n \"oxylabs\": {\n \"url\": \"https://mcp.oxylabs.io/mcp\",\n \"headers\": {\n \"Authorization\": \"Basic \",\n \"X-Oxylabs-AI-Studio-Api-Key\": \"YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\nThe server is also listed on [Smithery](https://smithery.ai/servers/oxylabsmcp/oxylabs-mcp).\n\n> **Note:** clients that only support OAuth for remote servers (for example, adding a custom\n> connector in the claude.ai web UI) cannot pass headers yet — OAuth sign-in is on our roadmap.\n> Use the local setup below with those clients in the meantime.\n\n### Option 2: Run locally\n\n#### Environment variables\n\nOxylabs MCP server supports the following environment variables:\n\n| Name | Description | Default |\n|-----------------------------|-----------------------------------------------|---------|\n| `OXYLABS_USERNAME` | Your Oxylabs Web Scraper API username | |\n| `OXYLABS_PASSWORD` | Your Oxylabs Web Scraper API password | |\n| `OXYLABS_AI_STUDIO_API_KEY` | Your Oxylabs AI Studio API key | |\n| `LOG_LEVEL` | Log level for the logs returned to the client | `INFO` |\n\nBased on the provided credentials, the server automatically exposes the corresponding tools:\n- If only `OXYLABS_USERNAME` and `OXYLABS_PASSWORD` are provided, the server exposes the Web Scraper API tools;\n- If only `OXYLABS_AI_STUDIO_API_KEY` is provided, the server exposes the AI Studio tools;\n- If all three are provided, the server exposes all tools.\n\n❗ **Important: only set the environment variables you have real credentials for.\nLeaving placeholder values will result in exposed tools that do not work.**\n\n#### Configure with uvx\n\nInstalls the [package from PyPI](https://pypi.org/project/oxylabs-mcp/) and runs it automatically:\n\n```json\n{\n \"mcpServers\": {\n \"oxylabs\": {\n \"command\": \"uvx\",\n \"args\": [\"oxylabs-mcp\"],\n \"env\": {\n \"OXYLABS_USERNAME\": \"YOUR_USERNAME\",\n \"OXYLABS_PASSWORD\": \"YOUR_PASSWORD\",\n \"OXYLABS_AI_STUDIO_API_KEY\": \"YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\n#### Configure with a local checkout\n\nUseful for development — runs the server from a local clone of this repository:\n\n```json\n{\n \"mcpServers\": {\n \"oxylabs\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"//oxylabs-mcp\",\n \"run\",\n \"oxylabs-mcp\"\n ],\n \"env\": {\n \"OXYLABS_USERNAME\": \"YOUR_USERNAME\",\n \"OXYLABS_PASSWORD\": \"YOUR_PASSWORD\",\n \"OXYLABS_AI_STUDIO_API_KEY\": \"YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\n#### Running as a remote HTTP server (self-hosting)\n\nThe server also supports the MCP streamable-HTTP transport. Start it with:\n\n```bash\nMCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp\n```\n\nWith the HTTP transport, credentials are passed per request instead of environment variables:\n\n| Credential | How to pass it |\n|---------------------------|--------------------------------------------------------------------------------------------------------|\n| Web Scraper API | `Authorization: Basic ` (standard HTTP Basic auth) |\n| Web Scraper API (alternative) | `X-Oxylabs-Username` and `X-Oxylabs-Password` headers |\n| AI Studio | `X-Oxylabs-AI-Studio-Api-Key` header |\n\nExample client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"oxylabs\": {\n \"url\": \"https://your-host:8000/mcp\",\n \"headers\": {\n \"Authorization\": \"Basic \",\n \"X-Oxylabs-AI-Studio-Api-Key\": \"YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\nAll tools are always listed regardless of provided credentials; calling a tool without the\ncredentials it needs returns an error message explaining exactly what to configure.\n\n#### Setup with Claude Desktop\n\nNavigate to **Claude → Settings → Developer → Edit Config** and add one of the configurations above to the `claude_desktop_config.json` file.\n\n#### Setup with Cursor AI\n\nNavigate to **Cursor → Settings → Cursor Settings → MCP**. Click **Add new global MCP server** and add one of the configurations above.\n\n\n## 📝 Logging\n\nThe server provides additional information about the tool calls in `notification/message` events:\n\n```json\n{\n \"method\": \"notifications/message\",\n \"params\": {\n \"level\": \"info\",\n \"data\": \"Create job with params: {\\\"url\\\": \\\"https://ip.oxylabs.io\\\"}\"\n }\n}\n```\n\n```json\n{\n \"method\": \"notifications/message\",\n \"params\": {\n \"level\": \"info\",\n \"data\": \"Job info: job_id=7333113830223918081 job_status=done\"\n }\n}\n```\n\n```json\n{\n \"method\": \"notifications/message\",\n \"params\": {\n \"level\": \"error\",\n \"data\": \"Error: request to Oxylabs API failed\"\n }\n}\n```\n\n\n## ✨ Key Features\n\n\n Scrape content from any site\n \n\n- Extract data from any URL, including complex single-page applications\n- Fully render dynamic websites using headless browser support\n- Choose full JavaScript rendering, HTML-only, or none\n- Emulate Mobile and Desktop viewports for realistic rendering\n\n\n\n\n Automatically get AI-ready data\n \n\n- Automatically clean and convert HTML to Markdown for improved readability\n- Use automated parsers for popular targets like Google, Amazon, and more\n\n\n\n\n Manage CAPTCHA & geo-restrictions\n \n\n- Navigate sophisticated automated request management systems with high success rate\n- Reliably scrape even the most complex websites\n- Get automatically rotating IPs from a proxy pool covering 195+ countries\n\n\n\n\n Flexible setup & cross-platform support\n \n\n- Set rendering and parsing options if needed\n- Feed data directly into AI models or analytics tools\n- Works on macOS, Windows, and Linux\n\n\n\n\n Built-in error handling and request management\n \n\n- Comprehensive error handling and reporting\n- Smart rate limiting and request management\n\n\n\n\n## Why Oxylabs MCP? 🕸️ ➜ 📦 ➜ 🤖\n\nImagine telling your LLM *\"Summarise the latest Hacker News discussion about GPT‑5\"* – and it simply answers.\nThe Oxylabs MCP server makes that happen by doing the boring parts for you:\n\n| What Oxylabs MCP does | Why it matters to you |\n|----------------------------------------------------------------------------|------------------------------------------|\n| **Manages automated request walls** with the Oxylabs global proxy network | Enables website access and anonymity |\n| **Renders JavaScript** in headless Chrome | Single‑page apps, sorted |\n| **Cleans HTML → Markdown** | Drop straight into vector DBs or prompts |\n| **Optional structured parsers** (Google, Amazon, etc.) | One‑line access to popular targets |\n\n---\n\n## 🛡️ License\n\nDistributed under the MIT License – see [LICENSE](LICENSE) for details.\n\n---\n\n## About Oxylabs\n\nEstablished in 2015, Oxylabs is a market-leading web intelligence collection\nplatform, driven by the highest business, ethics, and compliance standards,\nenabling companies worldwide to unlock data-driven insights.\n\n[](https://oxylabs.io/)\n\n
\n\n Made with ☕ by Oxylabs. Feel free to give us a ⭐ if MCP saved you a weekend.\n\n
\n\nmcp-name: io.oxylabs/oxylabs-mcp\n\n## Solutions made based on this MCP:\n[Michelin Detour](https://michelindetour.com/)\n",
"bytes": 12751,
"sha": "100c6195020c5d7502b26774afd7aa2c1b5055be8c83fbd69e4fde111a6bc29e",
"repo_slug": "oxylabs/oxylabs-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_oxylabs_oxylabs_mcp_f9366b53/readme"
}
![\"Oxylabs](\"https://storage.googleapis.com/oxylabs-public-assets/oxylabs_mcp.svg\")
\n