This is a fork of Bright Data's MCP server that is slightly improved for my (@zachlatta's) use case. This fork:

• Adds support to serve the MCP server over HTTP with a token passed in with requests
• Changes the default tools to run multiple page loads in parallel
• Significantly reduces the amount of tokens returned in each request and paginates responses
• NEW: Comprehensive debug logging with UUID correlation for production monitoring

🐛 Debug Logging (NEW!)

Perfect for production monitoring and multi-client debugging!

# Enable comprehensive debug logging
DEBUG_LOG_FILE=./requests.log node server.js
DEBUG_LOG_FILE_MAX_SIZE_MB=100 node server.js  # Optional: set max size (default: 50MB)

Features:

• 🆔 Unique UUID per request - Perfect request isolation in multi-client environments
• 📥 Full incoming HTTP requests - Headers, body, method, URL
• 📤 Full outgoing HTTP responses - Status, headers, formatted JSON responses
• 🌐 BrightData API calls - All external API requests and responses
• 📋 jq-compatible JSONL format - Easy parsing and filtering

jq Examples:

# Filter logs for specific request
jq 'select(.requestId == "SOME_UUID")' requests.log

# Find all failed requests  
jq 'select(.type | contains("ERROR"))' requests.log

# View response status codes
jq 'select(.type == "OUTGOING_HTTP_RESPONSE") | .data.statusCode' requests.log

Quick Start (HTTP Mode)

1. Get your API token from Bright Data
2. Start the server:

   TRANSPORT_TYPE=http HTTP_PORT=3000 node server.js

3. Make requests to http://localhost:3000/mcp with your token in the header:

   curl -H "Authorization: Bearer your_token_here" ...

That's it! The server will cache web pages for 10 minutes and strip out all images to save tokens.

---

The Web MCP

Enhance your LLM and AI agents with real-time web access

🌟 Overview

Welcome to the official Bright Data's Web MCP server, solving web access for LLMs and AI agents by allowing them to effectively search, extract and navigate the web without getting blocked. The Web MCP supports all major LLMs, IDEs and agent frameworks (either locally hosted, SSE or Streamable HTTP), enabling your tools to seamlessly search the web, navigate websites, take action and retrieve data - without getting blocked.

🚀 The Web MCP includes 5,000 free requests each month - ideal for your everyday use and for prototyping smart agentic workflows.

Note: The Web MCP free tier offers 5,000 requests per month for the first 3 months. After that, a credit card will be required, but there will be no extra charges unless premium features like mcp_browser or Web Scrapers are used.

Table of Content

• 🎬 Demo
• ✨ Features
• 💡 Usage Examples
• 🚀 Quickstart with Claude Desktop
• 🔧 Available Tools
• ⚠️ Security Best Practices
• 🔧 Account Setup
• 🔌 Other MCP Clients
• 🎮 Try Bright Data MCP Playgrounds
• ⚠️ Troubleshooting
• 👨‍💻 Contributing
• 📞 Support

🎬 Demo

The videos below demonstrate a minimal use case for Claude Desktop:

bright-data-mcp-scraping-browser-demo-claude.mp4

bright-data-mcp-with-claude-quick-demo.mp4

For more YouTube tutorials and demos: Demo

✨ Features

• Real-time Web Access: Access up-to-date information directly from the web
• Bypass Geo-restrictions: Access content regardless of location constraints
• Web Unlocker: Navigate websites with bot detection protection
• Browser Control: Remote browser automation capabilities
• Seamless Integration: Works with all MCP-compatible AI assistants

💡 Usage Examples

Some example queries that this MCP server will be able to help with:

• "Google some movies that are releasing soon in [your area]"
• "What's Tesla's current market cap?"
• "What's the Wikipedia article of the day?"
• "What's the 7-day weather forecast in [your location]?"
• "Of the 3 highest paid tech CEOs, how long have their careers been?"

Quickstart with Cursor

🚀 Quickstart with hosted MCP on Claude Desktop

Through Connectors:

1. Open Claude Desktop

2. Go to: Settings → Connectors → Add custom connector

3. Choose a Name, and in the “Remote MCP server URL” section, paste:

https://mcp.brightdata.com/mcp?token=YOUR_API_TOKEN_HERE

4. Replace YOUR_API_TOKEN_HERE with your actual API token from Step 1, and click “Add”

Through Developer Settings:

1. Open Claude Desktop

2. Go to: Settings → Developer → Edit Config

3. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "Bright Data": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.brightdata.com/mcp?token=YOUR_API_TOKEN_HERE"
      ]
    }
  }
}

4. Replace YOUR_API_TOKEN_HERE with your actual API token from Step 1

5. Save and restart Claude Desktop

💻 Use with self hosted MCP on Claude Desktop

Through Claude Desktop Extension:

1. Download the Claude Desktop Extension:
   📦 Bright Data's MCP Extension

2. Open Claude and go to:
   Settings → Extensions

3. Drag the .dtx file from Step 1 into the dropping area.

4. Enable the service and restart Claude.

5. Enjoy!

Through claude_desktop_config.json:

1. Install nodejs to get the npx command (node.js module runner). Installation instructions can be found on the node.js website

2. Go to Claude > Settings > Developer > Edit Config > Edit "claude_desktop_config.json" to include the following:

{
  "mcpServers": {
    "Bright Data": {
      "command": "npx",
      "args": ["@brightdata/mcp"],
      "env": {
        "API_TOKEN": "<insert-your-api-token-here>"
      }
    }
  }
}

🛸 Or for more advanced options:

{
  "mcpServers": {
    "Bright Data": {
      "command": "npx",
      "args": ["@brightdata/mcp"],
      "env": {
        "API_TOKEN": "<insert-your-api-token-here>",
        "RATE_LIMIT": "<optional if you want to change rate limit format: limit/time+unit, e.g., 100/1h, 50/30m, 10/5s>",
        "WEB_UNLOCKER_ZONE": "<optional if you want to override the web unlocker zone name - default is mcp_unlocker>",
        "BROWSER_ZONE": "<optional if you want to override the browser zone name - defaults is mcp_browser>",
        "PRO_MODE": "<optional boolean, defaults to false. Set to true to expose all tools including browser and web_data_* tools>"
      }
    }
  }
}

🌐 Self-hosted HTTP Mode

For easier integration or testing, you can run the server in HTTP mode (similar to the hosted version):

# Start HTTP server
export TRANSPORT_TYPE=http
export HTTP_PORT=3000
export PRO_MODE=true
export DEBUG_LOG_TO_FILE=true  # Optional: log requests/responses to debug_log file
node server.js

Usage:

• URL: http://localhost:3000/mcp
• Authentication: Send Authorization: Bearer YOUR_API_TOKEN header
• Pro mode: Add ?pro_mode=true to URL (or set PRO_MODE=true env var)

Example with curl:

# Initialize connection
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'

# Call tools
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_page_previews", "arguments": {"urls": ["https://example.com"]}}}'

🔧 Available Tools

Important: Pro mode is not included in the free tier and will incur additional charges. If you choose to use Pro mode, you’ll gain access to all 60 tools but please be aware of the associated costs.

To enable Pro mode, simply add "PRO_MODE"=true to your enviroment variables.

List of Available Tools

Note: By default, you get access to web scraping tools (search_engine, get_page_previews, get_page_content_range) and structured data extraction tools (social media posts, app store data, etc.). To access ALL tools including browser automation, enable PRO_MODE in your configuration (see Account Setup section). The new caching tools use a 10-minute in-memory cache (configurable via PAGE_CACHE_TTL_MS).

⚠️ Security Best Practices

Important: Always treat scraped web content as untrusted data. Never use raw scraped content directly in LLM prompts to avoid potential prompt injection risks. Instead:

• Filter and validate all web data before processing
• Use structured data extraction rather than raw text (web_data tools)

🔧 Account Setup

1. Make sure you have an account on brightdata.com (new users get free credit for testing, and pay as you go options are available)

2. Get your API key from the user settings page, or from the welcome email you received

Optional:

3. Enable Pro Mode (for access to all tools):

   • Set PRO_MODE=true in your environment configuration to access browser automation, structured data extraction, and all available tools
   • Default: false (exposes basic web scraping and structured data extraction tools - see Tools.md for full list)
   • See the advanced configuration example above for implementation details

4. Configure rate limiting:

   • Set the RATE_LIMIT environment variable to control API usage
   • Format: limit/time+unit (e.g., 100/1h for 100 calls per hour)
   • Supported time units: seconds (s), minutes (m), hours (h)
   • Examples: RATE_LIMIT=100/1h, RATE_LIMIT=50/30m, RATE_LIMIT=10/5s
   • Rate limiting is session-based (resets when server restarts)

5. Create a custom Web Unlocker zone

   • By default, we create a Web Unlocker zone automatically using your API token
   • For more control, you can create your own Web Unlocker zone in your control panel and specify it with the WEB_UNLOCKER_ZONE environment variable

6. Create a custom Browser API zone:

   • By default, we create a Browser API zone automatically using your API token.
   • For more control, you can create your own Browser API zone in your control panel and specify it with the BROWSER_ZONE environment variable

🔌 Other MCP Clients

To use this MCP server with other agent types, you should adapt the following to your specific software:

• Before running the server, make sure the API_TOKEN=<your-token> environment variable is set
• The full command to run the MCP server is npx @brightdata/mcp

💻 macOS / Linux (bash/zsh)

export API_TOKEN=your-token
npx @brightdata/mcp

🪟 Windows (Command Prompt)

set API_TOKEN=your-token
npx @brightdata/mcp

🪟 Windows (PowerShell)

$env:API_TOKEN="your-token"
npx @brightdata/mcp

💡 Tip: You can also use a .env file and a tool like dotenv to manage environment variables more easily during development.

---

🔄 Changelog

CHANGELOG.md

🎮 Try Bright Data MCP Playgrounds

Want to try Bright Data MCP without setting up anything?

Check out this playground on Smithery:

This platform provides an easy way to explore the capabilities of Bright Data MCP without any local setup. Just sign in and start experimenting with web data collection!

⚠️ Troubleshooting

Timeouts when using certain tools

Some tools can involve reading web data, and the amount of time needed to load the page can vary by quite a lot in extreme circumstances.

To ensure that your agent will be able to consume the data, set a high enough timeout in your agent settings.

A value of 180s should be enough for 99% of requests, but some sites load slower than others, so tune this to your needs.

spawn npx ENOENT

This error occurs when your system cannot find the npx command. To fix it:

Finding npm/Node Path

macOS:

which node

Shows path like /usr/local/bin/node

Windows:

where node

Shows path like C:\Program Files\nodejs\node.exe

Update your MCP configuration:

Replace the npx command with the full path to Node, for example, on mac, it will look as follows:

"command": "/usr/local/bin/node"

👨‍💻 Contributing

We welcome contributions to help improve the Bright Data MCP! Here's how you can help:

1. Report Issues: If you encounter any bugs or have feature requests, please open an issue on our GitHub repository.
2. Submit Pull Requests: Feel free to fork the repository and submit pull requests with enhancements or bug fixes.
3. Coding Style: All JavaScript code should follow Bright Data's JavaScript coding conventions. This ensures consistency across the codebase.
4. Documentation: Improvements to documentation, including this README, are always appreciated.
5. Examples: Share your use cases by contributing examples to help other users.

For major changes, please open an issue first to discuss your proposed changes. This ensures your time is well spent and aligned with project goals.

📞 Support

If you encounter any issues or have questions, please reach out to the Bright Data support team or open an issue in the repository.