Public Model Context Protocol server for Basecrawl.
Tools talk to the Basecrawl SaaS public API (/v1/*) with a Bearer API key (bc_…). They never use browser cookies or talk to the engine process (basecrawl serve) directly.
| Tool | SaaS route |
|---|---|
scrape | POST /v1/scrape |
crawl | POST /v1/crawl |
map | POST /v1/map |
batch_scrape | POST /v1/batch/scrape |
get_job | GET /v1/crawl/{id} · /v1/batch/scrape/{id} · /v1/map/{id} |
credit_usage | GET /v1/team/credit-usage |
- Node.js 20+
- A running Basecrawl SaaS API (local default http://127.0.0.1:4410)
- An API key with the scopes you need (
scrape,crawl,map,batch,read_usage)
pnpm install
pnpm build| Variable | Required | Default | Description |
|---|---|---|---|
BASECRAWL_API_KEY | yes | — | Bearer key (bc_…). Never commit this. |
BASECRAWL_API_URL | no | http://127.0.0.1:4410 | SaaS API base URL (no trailing slash) |
Copy .env.example to a gitignored .env (mode 600) for local scripts:
cp .env.example .env
chmod 600 .env
# edit BASECRAWL_API_KEY=bc_…For monorepo local seed credentials (gitignored):
set -a
# shellcheck disable=SC1091source ../basecrawl-api/.seed-credentials
set +aexport BASECRAWL_API_KEY=bc_…
export BASECRAWL_API_URL=http://127.0.0.1:4410 # optional
pnpm start
# or: node dist/index.js# or: pnpm devAdd to your Claude Desktop MCP config (path varies by OS):
{
"mcpServers": {
"basecrawl": {
"command": "node",
"args": ["/absolute/path/to/basecrawl-mcp/dist/index.js"],
"env": {
"BASECRAWL_API_URL": "http://127.0.0.1:4410",
"BASECRAWL_API_KEY": "bc_…"
}
}
}
}Same shape under Cursor MCP settings: command node, args pointing at dist/index.js, env with BASECRAWL_API_URL + BASECRAWL_API_KEY.
With basecrawl-api healthy on 4410 and a seed key:
set -a &&source ../basecrawl-api/.seed-credentials &&set +a
pnpm smoke# optional: curl parity
curl -sS -X POST "$BASECRAWL_API_URL/v1/scrape" \
-H "Authorization: Bearer $BASECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","formats":["markdown"]}'pnpm test# unit + live integration (live skipped if API down / no key)
pnpm typecheck # tsc --noEmitLive tests auto-load /projects/platform-network/basecrawl-api/.seed-credentials when present, or BASECRAWL_API_KEY from the environment. They hit only loopback SaaS.
Basecrawl residual risk applies on the scrape path: authenticity is cryptographically-anchored trust-but-audit, not trustless. Headless/Chromium side-channels and anti-bot challenges remain. This MCP does not claim commercial Web Unlocker parity, anonymous egress, or 100% unlock rates. Prefer the residual fields on scrape responses when present.
Apache-2.0