local mcp server
@crawlbrulee/mcp runs on your machine
with npx and an api key. it speaks stdio, wraps @crawlbrulee/sdk, and is open source
under Apache-2.0: source on GitHub . it
has the same seven tools as the hosted server, plus the fields the hosted one leaves out;
see mcp server.
get a key
the local server needs an api key. if you don’t have a crawlbrulee account yet, sign up . the free plan needs no credit card. then, in the dashboard menu, open tokens and click create token.
if the key stops working (the tools answer invalid_credentials), it’s expired, revoked or
mistyped. create a new one the same way, replace the old one, and start your agent again.
enter the key yourself, in one of the ways below. don’t paste it into your agent’s chat:
anything in the chat stays in its history. your agent can guide you through the setup
without seeing the key, then check it with the whoami tool.
install
1. put the key in your environment. add it to your shell profile (for example
~/.zshrc), then open a new terminal and start your agent from it:
export CRAWLBRULEE_API_KEY="cwbl_..."2. add the server, with no key in its config. it reads the variable each time it starts, so you can also do this step first.
Claude Code:
claude mcp add crawlbrulee -- npx -y @crawlbrulee/mcpCursor: add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). the env
line names the variable, so Cursor passes it on:
{
"mcpServers": {
"crawlbrulee": {
"command": "npx",
"args": ["-y", "@crawlbrulee/mcp"],
"env": { "CRAWLBRULEE_API_KEY": "${env:CRAWLBRULEE_API_KEY}" }
}
}
}Windsurf: add the same entry to its mcp_config.json, which you open from Windsurf’s
mcp settings.
Codex: add to ~/.codex/config.toml. Codex passes a variable to the server only when
it’s listed in env_vars. codex mcp add crawlbrulee -- npx -y @crawlbrulee/mcp writes
the first three lines; add the env_vars line yourself:
[mcp_servers.crawlbrulee]
command = "npx"
args = ["-y", "@crawlbrulee/mcp"]
env_vars = ["CRAWLBRULEE_API_KEY"]Gemini CLI: add to ~/.gemini/settings.json (or .gemini/settings.json in a
project). Gemini CLI passes a variable named like a key only when it’s listed in env,
and fills in $CRAWLBRULEE_API_KEY from your shell:
{
"mcpServers": {
"crawlbrulee": {
"command": "npx",
"args": ["-y", "@crawlbrulee/mcp"],
"env": { "CRAWLBRULEE_API_KEY": "$CRAWLBRULEE_API_KEY" }
}
}
}other stdio mcp hosts: set command: npx and args: ["-y", "@crawlbrulee/mcp"].
apps that don’t read your shell profile
an app opened from the dock or the start menu, like Claude Desktop, may not see the variable, and Claude Desktop’s config can’t name one. there, write the key into the config yourself.
Claude Desktop: open Settings → Developer → Edit Config, or the file itself:
~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
%APPDATA%\Claude\claude_desktop_config.json on Windows. add:
{
"mcpServers": {
"crawlbrulee": {
"command": "npx",
"args": ["-y", "@crawlbrulee/mcp"],
"env": { "CRAWLBRULEE_API_KEY": "cwbl_..." }
}
}
}then quit Claude Desktop and open it again.
other ways to enter the key
VS Code can ask for the key in a masked prompt when the server first starts, and store
it for you. add to .vscode/mcp.json:
{
"inputs": [
{
"type": "promptString",
"id": "crawlbrulee-api-key",
"description": "crawlbrulee api key",
"password": true
}
],
"servers": {
"crawlbrulee": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@crawlbrulee/mcp"],
"env": { "CRAWLBRULEE_API_KEY": "${input:crawlbrulee-api-key}" }
}
}
}the key in the config: run this in your own terminal, not through the agent (and not
with the ! prefix, which adds the command and its output to the chat):
claude mcp add crawlbrulee \
--env CRAWLBRULEE_API_KEY=cwbl_... \
-- npx -y @crawlbrulee/mcpconfiguration
| env var | required | description |
|---|---|---|
CRAWLBRULEE_API_KEY | yes | api key sent as Authorization: Bearer …. |
the key is read on the first tool call, so a typo shows up as a clear tool error, not as a server that won’t start.
what only the local server has
the local tools take every field the api takes, including the ones the hosted server leaves
out: headers and cookies, extract.raw_html, the screenshot’s viewport and
actions, and webhook on scrape_async. map returns up to 5000 urls a page unless you
set limit. the tools themselves are listed on mcp server.
get told when a job is done
scrape_async also takes an optional webhook: { url, metadata }. when the job finishes,
we send one signed scrape.complete POST to that url, with metadata echoed back under
data.metadata, so an agent can skip polling. see
webhook verification.
when a call fails
a failed call comes back as an mcp error result: [<errorName>] <message>, with
(HTTP <status>) added only when an http status applies. if CRAWLBRULEE_API_KEY isn’t
set where the server runs, calls fail with a missing_api_key error instead of the server
failing to start, so an agent can act on the error name either way. see errors
for every name.