Basecrawl MCP

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

Requirements

• 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)

Install

pnpm install
pnpm build

Configuration

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=SC1091
source ../basecrawl-api/.seed-credentials
set +a

Run (stdio)

export BASECRAWL_API_KEY=bc_…
export BASECRAWL_API_URL=http://127.0.0.1:4410   # optional
pnpm start
# or: node dist/index.js
# or: pnpm dev

Claude Desktop

Add 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_…"
      }
    }
  }
}

Cursor

Same shape under Cursor MCP settings: command node, args pointing at dist/index.js, env with BASECRAWL_API_URL + BASECRAWL_API_KEY.

Smoke against local API

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"]}'

Tests

pnpm test          # unit + live integration (live skipped if API down / no key)
pnpm typecheck     # tsc --noEmit

Live tests auto-load /projects/platform-network/basecrawl-api/.seed-credentials when present, or BASECRAWL_API_KEY from the environment. They hit only loopback SaaS.

Honesty

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.

License

Apache-2.0