Skip to main content
skill CX Codex

brightdata-mcp — Claude Code skill: setup and installation

The brightdata-mcp Claude Code skill explains how to connect Bright Data tools through MCP and choose which ones an agent can use. It activates during MCP client setup or tool-routing work.

MIT 184 installs ★ 272 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add brightdata/skills --skill brightdata-mcp -a claude-code
Open on GitHub

What brightdata-mcp does

The skill covers connecting Bright Data to an AI app or agent over MCP, then configuring its runtime tool choices. It distinguishes the hosted Remote server from the self-hosted @brightdata/mcp package, including their authentication methods and tool filters: groups= and tools= for Remote, GROUPS and TOOLS for Local.

For data from a known site, it directs the agent to find a ready-made scraper, inspect its inputs, and run it; page content can be retrieved as Markdown. It also points to setup and routing guidance. A Bright Data account API key is required: Remote accepts it in a URL or uses OAuth 2.1, while Local reads API_TOKEN. Tool names and configurations can differ between Remote and Local, so their working configs are not interchangeable.

What it helps with

  • connect an MCP client to Bright Data
  • choose between Remote and Local
  • filter the tools exposed to an agent
  • route a request to a suitable scraper

Example prompts for the agent

  • Connect Claude Code to Bright Data over MCP and compare the Remote and Local options.
  • Set the GROUPS filter for Bright Data's local server.
  • Which MCP tool should retrieve the contents of this page?

How to install brightdata-mcp

1Skills CLI (Vercel)

npx skills add brightdata/skills --skill brightdata-mcp -a claude-code

2Manually: put the files in place

~/.claude/skills/brightdata-mcp/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/brightdata-mcp/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about brightdata-mcp

How do I install brightdata-mcp in Claude Code?

Run npx skills add brightdata/skills --skill brightdata-mcp -a claude-code. The skill file is at ~/.claude/skills/brightdata-mcp/SKILL.md.

What does brightdata-mcp do?

It helps connect Bright Data through MCP, configure the tools an agent can access, and route requests to a suitable scraper. It covers both Remote and Local.

What does brightdata-mcp need to run?

A Bright Data account API key is required. Remote takes it in a URL or uses OAuth 2.1; Local reads it from API_TOKEN.

Source text

SKILL.md · MIT
---
name: brightdata-mcp
description: Bright Data's MCP server, the tool layer that gives an LLM agent live web access with no shell. Use when wiring Bright Data tools into an AI app or agent framework that picks its tools at run time, when connecting Claude, Cursor, or another MCP client to Bright Data, when choosing which MCP tools or groups to turn on, or when the user says MCP. Covers the Remote server hosted at mcp.brightdata.com and the Local self-hosted @brightdata/mcp package, and which tool each job should route to. Not for the agent doing the job itself from a shell, which is brightdata-cli. Not for fixed repeated code in an app, which is brightdata-sdk. Not for install or auth problems, which is agent-onboarding.
---

# Bright Data MCP

MCP is the interface for an AI app that decides at run time what to fetch. The
model reads a list of Bright Data tools and picks one per turn. There is no
shell to run and no code path to edit between turns, so the tool list you expose
and the routing rules you write are the entire product surface.

If a human or a coding agent is going to run the work from a terminal, that is
`brightdata-cli`. If the same job runs on a schedule from your own code, that is
`brightdata-sdk`. MCP is for run-time choice.

## Two variants that have drifted

Bright Data ships two, and the vendor calls them Remote (the hosted service at
`mcp.brightdata.com`) and Local (the self-hosted `@brightdata/mcp` package).

| | Remote | Local |
|---|---|---|
| Endpoint | `https://mcp.brightdata.com/mcp` (Streamable HTTP) or `/sse` | `npx @brightdata/mcp` over stdio |
| Auth | `?token=` on the URL for a client you control, or OAuth 2.1 (Bearer header, browser sign-in) when someone else runs the client | `API_TOKEN` env var |
| Tool config | URL query params `groups=` and `tools=` | env vars `GROUPS` and `TOOLS` |
| Default tool list | every tool on, 31 of them; `groups=` or `tools=` narrows it | every tool on, 32 of them; `GROUPS` or `TOOLS` narrows it |

The published package is `@brightdata/mcp`. Remote tracks its
own release line. Do not assume a tool name present in one is present in the
other, and do not carry a working config across. Confirm against the variant
actually in use.

## The key

Both `?token=` and `API_TOKEN` take the account API key. Find it the way the
CLI does: `BRIGHTDATA_API_KEY` if set, else `api_key` in the `credentials.json`
that `bdata login` writes (Linux `~/.config/brightdata-cli/`, macOS
`~/Library/Application Support/brightdata-cli/`, Windows
`%USERPROFILE%\AppData\Roaming\brightdata-cli\`). After login the variable is normally empty and
the key is only in the file: that is a logged-in machine, not a missing key,
so read it in code and never print it. To check that it exists, run
`node scripts/check-auth.mjs` from the `agent-onboarding` skill (it never
prints the key); never `cat`, `echo` or `jq` the file or the variable. To
pass it into a config or URL, read it inside the program or command that writes
the config, and keep it out of anything that prints (the shell-specific reads
are in that skill's `references/auth.md`). Neither exists: hand off to
`agent-onboarding`. Never ask the user to paste a key into chat.

## The routing default

Records from a site the agent can name go to a pre-built scraper:
`search_scrapers` to find it, `get_scraper_details` to see its inputs, then
`run_scraper`. Page content goes to `scrape_as_markdown`. Raw unlocked HTML through `scrape_as_html`
is the last resort, not the opening move. This is the misroute that burns the
most tokens and returns the worst data, so read the rule before writing prompts
or tool descriptions.

## References

- **references/setup.md** - open when connecting a client for the first time,
  when the agent sees the wrong number of tools, or when deciding between Remote
  and Local. Covers both installs, auth, zones, and the `GROUPS` and `TOOLS`
  filters.
- **references/choosing-tools.md** - open before writing the system prompt or
  tool guidance for an agent, or when an agent is scraping raw HTML for data a
  ready scraper already returns. Covers the full tool inventory and the routing
  table.

© brightdata · MIT · brightdata/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set14

The whole set →
scraper-builder scraper-builder takes you from "I want data from site X" to a working scraper: site analysis, Bright Data API choice, selectors, pagination. CX Codex +1 415installs design-mirror The design-mirror skill reads a website’s visual language and applies it to an existing codebase. Use it when a UI needs to follow a reference site’s look. CX Codex +1 353installs fetch fetch — a skill for Claude Code retrieves a web page as markdown, HTML, or a screenshot. Resolves bot challenges and 403 blocks using Bright Data Web Unlocker. CX Codex +1 186installs billing billing — a skill for Claude Code and Codex that checks Bright Data balance, inspects spend per zone, and estimates upcoming job costs. CX Codex +1 185installs browser This skill offloads local browser automation tasks to cloud infrastructure. It redirects traffic from drivers like Playwright, Puppeteer, or Selenium through a remote proxy server. CX Codex +1 183installs instagram This Claude Code skill fetches Instagram profiles, posts, Reels, and comments as JSON. It activates for requests about account followers, post likes, or recent content. CX Codex +1 182installs datasets Identifies available pre-collected datasets in the marketplace to replace manual scraping. It triggers when a large generic corpus is requested. CX Codex +1 180installs brightdata-plugin brightdata-plugin is a Claude Code plugin that searches Google, collects web pages, and extracts structured data for agents working with live website information. ★ 272repo stars

Project sponsors

Companies that keep this analytics open