Skip to content
Back to search

oxylabs-mcp

Official Oxylabs MCP integration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oxylabs--oxylabs-mcp/badge.svg)](/listings/oxylabs--oxylabs-mcp)

HTML

<a href="/listings/oxylabs--oxylabs-mcp"><img src="/api/listings/oxylabs--oxylabs-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Oxylabs runs a hosted MCP server at:

https://mcp.oxylabs.io/mcp

Credentials are passed with request headers:

| Credential | Header | |--------------------------------|------------------------------------------------------------------| | Web Scraper API | `Authorization: Basic <base64(username:password)>` | | Web Scraper API (alternative) | `X-Oxylabs-Username` and `X-Oxylabs-Password` | | AI Studio | `X-Oxylabs-AI-Studio-Api-Key` |

Setup with **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"

Setup with **Cursor** or any client that supports remote MCP servers with custom headers:

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

The server is also listed on [Smithery](https://smithery.ai/servers/oxylabsmcp/oxylabs-mcp).

> **Note:** clients that only support OAuth for remote servers (for example, adding a custom > connector in the claude.ai web UI) cannot pass headers yet — OAuth sign-in is on our roadmap. > Use the local setup below with those clients in the meantime.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 371 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://storage.googleapis.com/oxylabs-public-assets/oxylabs_mcp.svg" alt="Oxylabs + MCP">
  3. </p>
  4. <h1 align="center" style="border-bottom: none;">
  5. Oxylabs MCP Server
  6. </h1>
  7. <p align="center">
  8. <em>The missing link between AI models and the real‑world web: one API that delivers clean, structured data from any site.</em>
  9. </p>
  10. <div align="center">
  11. [![pypi package](https://img.shields.io/pypi/v/oxylabs-mcp?color=%2334D058&label=pypi%20package)](https://pypi.org/project/oxylabs-mcp/)
  12. [![](https://dcbadge.vercel.app/api/server/eWsVUJrnG5?style=flat)](https://discord.gg/Pds3gBmKMH)
  13. [![Licence](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  14. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/f6a9c0bc-83a6-4f78-89d9-f2cec4ece98d)
  15. ![Coverage badge](https://raw.githubusercontent.com/oxylabs/oxylabs-mcp/coverage/coverage-badge.svg)
  16. <br/>
  17. <a href="https://glama.ai/mcp/servers/@oxylabs/oxylabs-mcp">
  18. <img width="380" height="200" src="https://glama.ai/mcp/servers/@oxylabs/oxylabs-mcp/badge" alt="Oxylabs Server MCP server" />
  19. </a>
  20. </div>
  21. ---
  22. ## Disclaimer
  23. This repository is still fully supported, but if you are using Oxylabs Web API please refer to Web API MCP repository:
  24. [Web API MCP](https://github.com/oxylabs/web-api-mcp)
  25. ## 📖 Overview
  26. The 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.
  27. It is built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), the open standard for connecting AI assistants to external tools and data.
  28. mcp-name: io.oxylabs/oxylabs-mcp
  29. ## 🛠️ MCP Tools
  30. Oxylabs MCP provides two sets of tools that can be used together or independently:
  31. ### Oxylabs Web Scraper API tools
  32. 1. **universal_scraper**: scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output;
  33. 2. **google_search_scraper**: extracts results from Google Search, with optional parsing into structured JSON;
  34. 3. **amazon_search_scraper**: scrapes Amazon search result pages, with optional parsing into structured JSON;
  35. 4. **amazon_product_scraper**: extracts data from individual Amazon product pages.
  36. ### Oxylabs AI Studio tools
  37. 5. **ai_scraper**: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;
  38. 6. **ai_crawler**: crawls a website from a starting URL based on a prompt and collects data across multiple pages;
  39. 7. **ai_browser_agent**: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;
  40. 8. **ai_search**: searches the web and optionally returns Markdown content of each result;
  41. 9. **ai_map**: maps a website's URLs, filtered by keywords or a prompt;
  42. 10. **generate_schema**: generates an OpenAPI-format JSON schema for structured extraction with the AI tools above.
  43. ## ✅ Prerequisites
  44. Before you begin, make sure you have **at least one** of the following:
  45. - **Oxylabs Web Scraper API account**: obtain an API token (or your username and password) from the [Oxylabs dashboard](https://dashboard.oxylabs.io/) (1-week free trial available);
  46. - **Oxylabs AI Studio API key**: obtain your API key from [Oxylabs AI Studio](https://aistudio.oxylabs.io/settings/api-key) (1000 credits free).
  47. To run the server locally (Option 2 below) you will also need the [uv](https://docs.astral.sh/uv/) package manager:
  48. ```bash
  49. # macOS and Linux
  50. curl -LsSf https://astral.sh/uv/install.sh | sh
  51. ```
  52. ```powershell
  53. # Windows
  54. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  55. ```
  56. ## 📦 Configuration
  57. There are two ways to use the server: connect to the **hosted instance** (no installation)
  58. or **run it locally** with credentials in environment variables.
  59. ### Option 1: Hosted server (no installation)
  60. Oxylabs runs a hosted MCP server at:
  61. ```
  62. https://mcp.oxylabs.io/mcp
  63. ```
  64. Credentials are passed with request headers:
  65. | Credential | Header |
  66. |-----------------------------------------------|-----------------------------------------------------|
  67. | Web Scraper API token (recommended) | `Authorization: Bearer <token>` |
  68. | Web Scraper API token (alternative) | `X-Oxylabs-Api-Token` |
  69. | Web Scraper API username and password | `Authorization: Basic <base64(username:password)>` |
  70. | Web Scraper API username and password (alt.) | `X-Oxylabs-Username` and `X-Oxylabs-Password` |
  71. | AI Studio | `X-Oxylabs-AI-Studio-Api-Key` |
  72. If both an API token and a username and password are passed, the token is used.
  73. Setup with **Claude Code**:
  74. ```bash
  75. claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  76. --header "Authorization: Bearer YOUR_API_TOKEN" \
  77. --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"
  78. ```
  79. Setup with **Cursor** or any client that supports remote MCP servers with custom headers:
  80. ```json
  81. {
  82. "mcpServers": {
  83. "oxylabs": {
  84. "url": "https://mcp.oxylabs.io/mcp",
  85. "headers": {
  86. "Authorization": "Bearer YOUR_API_TOKEN",
  87. "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. The server is also listed on [Smithery](https://smithery.ai/servers/oxylabsmcp/oxylabs-mcp).
  94. > **Note:** clients that only support OAuth for remote servers (for example, adding a custom
  95. > connector in the claude.ai web UI) cannot pass headers yet — OAuth sign-in is on our roadmap.
  96. > Use the local setup below with those clients in the meantime.
  97. ### Option 2: Run locally
  98. #### Environment variables
  99. Oxylabs MCP server supports the following environment variables:
  100. | Name | Description | Default |
  101. |-----------------------------|-----------------------------------------------|---------|
  102. | `OXYLABS_API_TOKEN` | Your Oxylabs Web Scraper API token | |
  103. | `OXYLABS_USERNAME` | Your Oxylabs Web Scraper API username | |
  104. | `OXYLABS_PASSWORD` | Your Oxylabs Web Scraper API password | |
  105. | `OXYLABS_AI_STUDIO_API_KEY` | Your Oxylabs AI Studio API key | |
  106. | `LOG_LEVEL` | Log level for the logs returned to the client | `INFO` |
  107. For the Web Scraper API tools, set either `OXYLABS_API_TOKEN` or both `OXYLABS_USERNAME` and
  108. `OXYLABS_PASSWORD`. If both are set, the token is used. For the AI Studio tools, set
  109. `OXYLABS_AI_STUDIO_API_KEY`.
  110. All tools are always listed; calling a tool without the credentials it needs returns an error
  111. message explaining what to configure.
  112. ❗ **Important: only set the environment variables you have real credentials for.
  113. Placeholder values make tool calls fail.**
  114. #### Configure with uvx
  115. Installs the [package from PyPI](https://pypi.org/project/oxylabs-mcp/) and runs it automatically:
  116. ```json
  117. {
  118. "mcpServers": {
  119. "oxylabs": {
  120. "command": "uvx",
  121. "args": ["oxylabs-mcp"],
  122. "env": {
  123. "OXYLABS_API_TOKEN": "YOUR_API_TOKEN",
  124. "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
  125. }
  126. }
  127. }
  128. }
  129. ```
  130. #### Configure with a local checkout
  131. Useful for development — runs the server from a local clone of this repository:
  132. ```json
  133. {
  134. "mcpServers": {
  135. "oxylabs": {
  136. "command": "uv",
  137. "args": [
  138. "--directory",
  139. "/<absolute-path-to-folder>/oxylabs-mcp",
  140. "run",
  141. "oxylabs-mcp"
  142. ],
  143. "env": {
  144. "OXYLABS_API_TOKEN": "YOUR_API_TOKEN",
  145. "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
  146. }
  147. }
  148. }
  149. }
  150. ```
  151. #### Running as a remote HTTP server (self-hosting)
  152. The server also supports the MCP streamable-HTTP transport. Start it with:
  153. ```bash
  154. MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp
  155. ```
  156. With the HTTP transport, credentials are passed per request instead of environment variables:
  157. | Credential | How to pass it |
  158. |-----------------------------------------------|-----------------------------------------------------------------------|
  159. | Web Scraper API token (recommended) | `Authorization: Bearer <token>` |
  160. | Web Scraper API token (alternative) | `X-Oxylabs-Api-Token` header |
  161. | Web Scraper API username and password | `Authorization: Basic <base64(username:password)>` (HTTP Basic auth) |
  162. | Web Scraper API username and password (alt.) | `X-Oxylabs-Username` and `X-Oxylabs-Password` headers |
  163. | AI Studio | `X-Oxylabs-AI-Studio-Api-Key` header |
  164. Example client configuration:
  165. ```json
  166. {
  167. "mcpServers": {
  168. "oxylabs": {
  169. "url": "https://your-host:8000/mcp",
  170. "headers": {
  171. "Authorization": "Bearer YOUR_API_TOKEN",
  172. "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
  173. }
  174. }
  175. }
  176. }
  177. ```
  178. All tools are always listed regardless of provided credentials; calling a tool without the
  179. credentials it needs returns an error message explaining exactly what to configure.
  180. #### Setup with Claude Desktop
  181. Navigate to **Claude → Settings → Developer → Edit Config** and add one of the configurations above to the `claude_desktop_config.json` file.
  182. #### Setup with Cursor AI
  183. Navigate to **Cursor → Settings → Cursor Settings → MCP**. Click **Add new global MCP server** and add one of the configurations above.
  184. ## 📝 Logging
  185. The server provides additional information about the tool calls in `notification/message` events:
  186. ```json
  187. {
  188. "method": "notifications/message",
  189. "params": {
  190. "level": "info",
  191. "data": "Create job with params: {\"url\": \"https://ip.oxylabs.io\"}"
  192. }
  193. }
  194. ```
  195. ```json
  196. {
  197. "method": "notifications/message",
  198. "params": {
  199. "level": "info",
  200. "data": "Job info: job_id=7333113830223918081 job_status=done"
  201. }
  202. }
  203. ```
  204. ```json
  205. {
  206. "method": "notifications/message",
  207. "params": {
  208. "level": "error",
  209. "data": "Error: request to Oxylabs API failed"
  210. }
  211. }
  212. ```
  213. ## ✨ Key Features
  214. <details>
  215. <summary><strong> Scrape content from any site</strong></summary>
  216. <br>
  217. - Extract data from any URL, including complex single-page applications
  218. - Fully render dynamic websites using headless browser support
  219. - Choose full JavaScript rendering, HTML-only, or none
  220. - Emulate Mobile and Desktop viewports for realistic rendering
  221. </details>
  222. <details>
  223. <summary><strong> Automatically get AI-ready data</strong></summary>
  224. <br>
  225. - Automatically clean and convert HTML to Markdown for improved readability
  226. - Use automated parsers for popular targets like Google, Amazon, and more
  227. </details>
  228. <details>
  229. <summary><strong> Manage CAPTCHA & geo-restrictions</strong></summary>
  230. <br>
  231. - Navigate sophisticated automated request management systems with high success rate
  232. - Reliably scrape even the most complex websites
  233. - Get automatically rotating IPs from a proxy pool covering 195+ countries
  234. </details>
  235. <details>
  236. <summary><strong> Flexible setup & cross-platform support</strong></summary>
  237. <br>
  238. - Set rendering and parsing options if needed
  239. - Feed data directly into AI models or analytics tools
  240. - Works on macOS, Windows, and Linux
  241. </details>
  242. <details>
  243. <summary><strong> Built-in error handling and request management</strong></summary>
  244. <br>
  245. - Comprehensive error handling and reporting
  246. - Smart rate limiting and request management
  247. </details>
  248. ## Why Oxylabs MCP? &nbsp;🕸️ ➜ 📦 ➜ 🤖
  249. Imagine telling your LLM *"Summarise the latest Hacker News discussion about GPT‑5"* – and it simply answers.
  250. The Oxylabs MCP server makes that happen by doing the boring parts for you:
  251. | What Oxylabs MCP does | Why it matters to you |
  252. |----------------------------------------------------------------------------|------------------------------------------|
  253. | **Manages automated request walls** with the Oxylabs global proxy network | Enables website access and anonymity |
  254. | **Renders JavaScript** in headless Chrome | Single‑page apps, sorted |
  255. | **Cleans HTML → Markdown** | Drop straight into vector DBs or prompts |
  256. | **Optional structured parsers** (Google, Amazon, etc.) | One‑line access to popular targets |
  257. ---
  258. ## 🛡️ License
  259. Distributed under the MIT License – see [LICENSE](LICENSE) for details.
  260. ---
  261. ## About Oxylabs
  262. Established in 2015, Oxylabs is a market-leading web intelligence collection
  263. platform, driven by the highest business, ethics, and compliance standards,
  264. enabling companies worldwide to unlock data-driven insights.
  265. [![image](https://oxylabs.io/images/og-image.png)](https://oxylabs.io/)
  266. <div align="center">
  267. <sub>
  268. Made with ☕ by <a href="https://oxylabs.io">Oxylabs</a>. Feel free to give us a ⭐ and a follow if our MCP saved you a weekend.
  269. </sub>
  270. </div>
  271. ## Solutions made based on this MCP:
  272. [Michelin Detour](https://michelindetour.com/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.