brightdata-mcp-plus

brightdata-mcp-plus is a Model Context Protocol server that gives AI agents (Claude Code, Claude Desktop, Cursor, VS Code, any MCP client) reliable access to live web data: page fetching, search, 1,200+ pre-built scrapers, datasets and remote browsers.

It is a ground-up TypeScript rebuild of the official @brightdata/mcp, keeping its tool names and environment variables so it works as a drop-in replacement, and adding what it was missing: free direct fetching and local Chrome rendering, with Bright Data only as the fallback for bot walls, spending guards, caching, pagination, cancellation, retries, an SSRF guard, a built-in HTTP transport and a real test suite.

Unofficial project, not affiliated with Bright Data. Bright Data features (search, scrapers, unblocking, remote browsers) need your own Bright Data API token and are billed by Bright Data. Page fetching, including JavaScript apps rendered in your own Chrome, works with no account at all.

Contents

• Why it costs less
• Quick start
• Connect your client
• How page fetching works
• Tools
• Configuration
• Cost control
• Security model
• Architecture
• Compared with @brightdata/mcp
• Development
• FAQ

Why it costs less

Bright Data charges per request. Most pages an agent reads (docs, blogs, news, GitHub, package registries, Wikipedia) don't block ordinary requests, so paying a proxy network to fetch them is wasted money. This server tries two free routes first:

1. Direct fetch from your machine: plain HTTP, fast, works for most of the web.
2. Local headless Chrome (or Edge) when the page is a JavaScript-only app shell: Spotify, Instagram, YouTube, TikTok, Figma, Duolingo and other single-page apps render for free on your own browser.

Only real bot walls (Cloudflare challenges, DataDome, PerimeterX, CAPTCHAs) go to Bright Data. Repeated fetches come from a cache, also free.

That screenshot is a real run of scripts/live-smoke.mjs against live websites with no API token. Wikipedia, Hacker News and GitHub were fetched directly. Spotify, Instagram, YouTube and TikTok, which send an empty shell to plain HTTP clients, were rendered in a local headless Chrome and returned their real content (follower counts, bios, video and track lists). G2's Cloudflare challenge and Reddit's CAPTCHA were detected; with a token these go to Bright Data automatically. An attempt to read the cloud-metadata address was refused by the SSRF guard. Every result tells the agent how it was fetched:

[server] Fetched directly (free).
[server] Rendered in a local headless browser (free): the page needs JavaScript.
[server] Fetched via Bright Data (billed): free routes were not usable (needs_javascript > render:captcha).
[server] Served from cache (originally via free direct fetch; no cost).

Quick start

Requires Node.js 22+. Google Chrome or Microsoft Edge is optional: with one installed, JavaScript apps are rendered locally for free; without one they go to Bright Data (or fail in free mode).

git clone https://github.com/wikydtron/brightdata-mcp-plus.git
cd brightdata-mcp-plus
npm install        # also builds (prepare script)
npm test           # optional: 70 tests, ~10 s

Or run it straight from GitHub without cloning:

npx -y github:wikydtron/brightdata-mcp-plus --list-tools

Free mode (no account): start it without API_TOKEN. You get scrape_as_markdown, scrape_batch, scrape_as_html, extract and session_stats, fetching directly and rendering JavaScript apps in your local Chrome or Edge (found automatically; set CHROME_PATH otherwise). Add BROWSER_CDP_ENDPOINT to drive your own Chrome with the interactive browser tools too.

Full mode: set API_TOKEN to unlock search, scrapers, datasets, AI-insights and Bright Data's remote browsers. Page fetching still tries the free routes (direct, then local Chrome) first, so only bot-walled pages are billed. Check your token and zones first:

API_TOKEN=your_token node dist/src/index.js --check

Connect your client

claude mcp add brightdata -e API_TOKEN=your_token -- node /absolute/path/to/brightdata-mcp-plus/dist/src/index.js

{
  "mcpServers": {
    "brightdata": {
      "command": "node",
      "args": ["/absolute/path/to/brightdata-mcp-plus/dist/src/index.js"],
      "env": { "API_TOKEN": "your_token", "BUDGET_MAX_REQUESTS": "500" }
    }
  }
}

{
  "mcpServers": {
    "brightdata": {
      "command": "node",
      "args": ["/absolute/path/to/brightdata-mcp-plus/dist/src/index.js"],
      "env": { "API_TOKEN": "your_token" }
    }
  }
}

node dist/src/index.js --transport http --port 3000

docker build -t brightdata-mcp-plus .
docker run -i --rm -e API_TOKEN=your_token brightdata-mcp-plus

How page fetching works

Details:

• Bot-wall detection looks for Cloudflare challenges, DataDome, Imperva, PerimeterX, AWS WAF, Google's "unusual traffic" page, CAPTCHA widgets and JavaScript-only shells. CAPTCHA keywords only count on short pages, so an article with a reCAPTCHA contact form is still fetched for free. Rendered pages are classified again, so a bot wall that only appears after JavaScript runs is still caught.
• Local rendering uses your installed Chrome or Edge through playwright-core (no browser download). One headless browser is shared by all sessions, each render gets a fresh incognito context, images, media and fonts are skipped, and the browser closes after 2 idle minutes. A render finishes as soon as the app has produced text or its network goes quiet, so an empty shell fails over in about a second instead of waiting out a timeout. The first render after the browser has been closed can take several seconds longer while it starts. It renders pages; it does not try to evade bot detection, so walls still go to Bright Data, which exists for that.
• Host memory: for 30 minutes, a host that needed rendering skips the direct attempt, and a host that blocked goes straight to Bright Data.
• Country routing (country: "de") always uses Bright Data, since geo-targeting needs a proxy.
• Direct fetches follow up to 5 redirects, decode gzip/deflate/brotli, honour the page charset, stop at 15 s and 10 MB, and convert HTML to Markdown with absolute links.
• Limits: apps that keep streaming data after the first paint (Google Maps, live trading charts) may render only their UI chrome. For structured data from those, use a pre-built scraper (search_scrapers "google maps") or the interactive scraping_browser_* tools.

Tools (34)

Prompts: web_scraping_strategy and diagnose_scraping_approach (takes a url).

Configuration

All settings are environment variables (names compatible with @brightdata/mcp). Run --help for CLI flags.

Cost control

• Budget: BUDGET_MAX_REQUESTS=500 stops a session before its 501st billable unit. Units are reserved before each call, so parallel calls can't overshoot together. Cached pages stay available after the budget is spent.
• Scraper guard: run_scraper refuses discover_by_* runs whose worst case (inputs × limit_per_input) exceeds MAX_RECORDS_PER_RUN, and checks required input fields before triggering, so typos are never billed.
• No double billing: job triggers are retried only when Bright Data rejected them (429), never after a timeout that may have started a job.
• Visibility: session_stats returns

{
  "fetch_strategy": "auto",
  "local_rendering": "on",
  "billable": { "unlocker_requests": 3, "scraper_records": 10, "dataset_records": 0, "browser_navigations": 0 },
  "estimated_cost_usd": 0.0195,
  "free": { "direct_fetches": 42, "local_renders": 9, "fallbacks": 3, "estimated_savings_usd": 0.0765 },
  "budget": { "max": 500, "used": 13, "remaining": 487 },
  "tools": { "scrape_as_markdown": { "calls": 45, "errors": 0, "cache_hits": 6, "p50_ms": 410, "p95_ms": 1890 } }
}

Security model

Architecture

src/
  index.ts            CLI: flags, --check, --list-tools, stdio startup, graceful shutdown
  config.ts           Validated config (env + flags)
  server.ts           createSession(): one isolated McpServer + services; the tool pipeline
  http/client.ts      The only path to the Bright Data API: auth, timeouts, retries, concurrency, typed errors
  http/server.ts      Streamable HTTP transport with per-session isolation
  services/           pages (direct → render → Bright Data), direct (SSRF-safe fetch + classifier),
                      render (local headless Chrome), unlocker, serp, scrapers, datasets, assistant,
                      browser, zones
  tools/              Tool definitions (zod schemas, annotations), grouped by area
  security/           Untrusted-content wrapping, prompt-injection content gate
  usage.ts            Stats, budget reservations, rate limiting, savings
  util/               Cache, semaphore, pagination, Markdown minifier, redaction

Compared with @brightdata/mcp

Development

npm run build          # tsc
npm test               # build + 70 tests (browser and render tests use local Chrome/Edge if found)
npm run typecheck
node scripts/live-smoke.mjs                                 # real sites, free mode, no cost
node scripts/live-smoke.mjs --json assets/src/live-run.json # refresh demo data
node scripts/render-assets.mjs                              # re-render README images (needs Chrome/Edge)

Test suites: unit (config, cache, semaphore, errors, security, SERP, pagination, scoring, budget), client (retries, Retry-After, timeouts, cancellation, headers), e2e (all tool families through a real MCP client), direct (direct fetching, bot-wall detection, fallback, SSRF, free mode), render (local Chrome: client-rendered pages, XHR, walls that appear after JavaScript, host memory, in-browser SSRF guard), http (multi-tenant HTTP), stdio (the built CLI as a subprocess) and browser (a real headless Chrome over CDP).

FAQ

Is it free? Fetching pages directly and rendering them in your own Chrome is free. Bright Data's own services (search, scrapers, unblocking protected sites, remote browsers) run on their infrastructure and are billed to your Bright Data account; their free tier is 5,000 requests a month. This server just makes sure you only use them when needed.

Why did a page cost a request? The result note says why, e.g. cloudflare_challenge or needs_javascript > render:captcha (a JavaScript app that showed a CAPTCHA even to a real browser). Use FETCH_STRATEGY=direct to never pay, at the cost of failing on protected sites.

Do I need Chrome? No. Without Chrome or Edge the render step is skipped: the first page that needs it falls through to Bright Data with the reason render:unavailable, and from then on session_stats shows local_rendering: "unavailable (no Chrome/Edge found)". Set CHROME_PATH if your browser is in a non-standard place, or LOCAL_RENDER=off to skip the attempt entirely.

Is direct fetching and local rendering allowed? Both are ordinary requests from your machine, the same as opening the page in your browser. You are responsible for respecting each site's terms and robots rules.

Is this official? No. It's an independent MIT-licensed project derived from brightdata/brightdata-mcp (MIT, see LICENSE.upstream).

License

MIT