brightdata-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

MCP 是一种接口，供 AI app 在运行时决定要抓取什么。模型会读取 Bright Data 的工具列表，并在每一轮选择一个。无需运行 shell，也无需在轮次之间编辑代码路径，因此，你暴露的工具列表以及编写的路由规则，就是完整的产品使用界面。

如果由人类或 coding agent 从终端执行任务，应使用

brightdata-cli

。如果同一任务需要通过自己的代码定时运行，应使用

brightdata-sdk

。MCP 适用于运行时的动态选择。

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.

Bright Data 提供了两个版本，厂商将它们分别称为 Remote（托管服务，地址为

mcp.brightdata.com

）和 Local（自行托管的

@brightdata/mcp

包）。

	Remote	Local
端点	`https://mcp.brightdata.com/mcp` （Streamable HTTP）或 `/sse`	通过 stdio 运行 `npx @brightdata/mcp`
认证	对于你控制的 client，在 URL 中使用 `?token=` ；当由他人运行 client 时，使用 OAuth 2.1（Bearer header、浏览器登录）	`API_TOKEN` 环境变量
工具配置	URL 查询参数 `groups=` 和 `tools=`	环境变量 `GROUPS` 和 `TOOLS`
默认工具列表	默认启用全部 31 个工具；可通过 `groups=` 或 `tools=` 缩减	默认启用全部 32 个工具；可通过 `GROUPS` 或 `TOOLS` 缩减

已发布的包名为

@brightdata/mcp

。Remote 维护自己的发布版本线。不要假定某个工具名在一个变体中存在，就一定存在于另一个变体中，也不要直接沿用其他变体的可用配置。请根据实际使用的变体进行确认。

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

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.

?token=

和

API_TOKEN

都需要使用账户的 API key。按照 CLI 的方式查找该 key：如果已设置

BRIGHTDATA_API_KEY

，则直接使用；否则读取

bdata login

写入的

credentials.json

中的

api_key

（Linux 路径为

~/.config/brightdata-cli/

，macOS 路径为

~/Library/Application Support/brightdata-cli/

，Windows 路径为

%USERPROFILE%\AppData\Roaming\brightdata-cli\

）。登录后，该变量通常为空，key 仅存在于文件中。这表示机器已经登录，并非缺少 key，因此应在代码中读取，且绝不要打印。

要检查 key 是否存在，请运行

agent-onboarding

skill 中的

node scripts/check-auth.mjs

（它绝不会打印 key）；绝不要使用

cat

、

echo

或

jq

读取文件或变量。要将 key 传入配置或 URL，应在写入配置的程序或命令内部读取，并确保任何会输出内容的环节都不包含它（针对不同 shell 的读取方式位于该 skill 的

references/auth.md

中）。如果两种方式都不存在，则转交

agent-onboarding

处理。绝不要让用户在聊天中粘贴 key。

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.

如果 agent 能够明确指出目标站点，应使用预构建的 scraper 获取该站点的记录：先用

search_scrapers

查找，再通过

get_scraper_details

查看输入参数，最后使用

run_scraper

。页面内容应使用

scrape_as_markdown

。通过

scrape_as_html

获取原始的已解锁 HTML 只应是最后手段，而不是首选。这种错误路由会浪费最多 token，并返回质量最差的数据，因此，在编写 prompt 或工具说明前，务必先阅读此规则。

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.

references/setup.md —— 首次连接 client、agent 看到的工具数量不正确，或需要在 Remote 和 Local 之间做选择时打开。涵盖两种安装方式、认证、zones，以及
```
GROUPS
```
和
```
TOOLS
```
过滤条件。
references/choosing-tools.md —— 在编写 agent 的 system prompt 或工具使用指南之前打开，或当 agent 正在抓取原始 HTML，而现成的 scraper 已经能够返回所需数据时打开。涵盖完整的工具清单和路由表。