Skip to Content

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/mcp

Cursor: 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/mcp

configuration

env varrequireddescription
CRAWLBRULEE_API_KEYyesapi 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.