How do I use Basecrawl MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Basecrawl MCP Scrape https://example.com and return markdown" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Basecrawl MCP

Official

by Basecrawl

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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)

Related MCP server: Dev Tool MCP

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

Available Tools

6 tools

batch_scrapeBatch scrape URLsA

Start a multi-URL batch scrape via POST /v1/batch/scrape. Returns a batch id; poll with get_job (kind=batch).

ParametersJSON Schema

Name	Required	Description
`urls`	Yes	List of absolute URLs to scrape in one batch job
`formats`	No	Optional formats applied to each URL
`concurrency`	No	Optional concurrency hint for the batch worker

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the async nature (returns a batch id to poll), which is critical. However, it does not mention potential failures, rate limits, or data persistence, leaving some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, action-first, with no fluff. Every sentence adds value: what the tool does and how to follow up.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description mentions the return value (batch id) and subsequent polling with get_job. For an initiator tool with 3 parameters, this provides enough context for correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 3 parameters. The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Start a multi-URL batch scrape', specifying the action and resource. It distinguishes from siblings like 'scrape' (single URL) and 'crawl' by emphasizing batch and multi-URL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the agent to poll with get_job (kind=batch) after starting, providing a clear workflow. It implies multi-URL usage, distinguishing from single scrape, but lacks explicit when-not or alternatives for concurrency and formats.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crawlStart crawl jobA

Start an async crawl job via POST /v1/crawl. Returns a job id; poll with get_job.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Seed URL for the crawl job
`limit`	No	Max pages to crawl (1–100)
`formats`	No	Optional content formats for discovered pages
`maxDepth`	No	Max crawl depth (0–10, default server-side)

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses async nature and that it returns a job id. With no annotations, more details (e.g., auth, rate limits, side effects) would improve understanding, but the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with essential information, followed by a clear instruction. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately covers the tool's purpose and workflow given the schema richness. Pairs well with get_job for completion, though could mention error/status handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides full parameter descriptions. The tool description adds no new meaning beyond restating the schema fields, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it starts an async crawl job, specifies the endpoint, and mentions the return type (job id). Distinguishes from sibling get_job by indicating polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to poll with get_job for results, implying async workflow. Does not explicitly exclude use cases or compare with other siblings like batch_scrape or map.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

credit_usageCredit usageA

Get org credit remaining / usage via GET /v1/team/credit-usage (requires read_usage scope on the API key).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that it is a GET request and requires a specific scope, which implies a safe read operation. Without annotations, this provides useful behavioral context. It could mention rate limits or response structure but is sufficient for a simple tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It conveys the purpose, method, and requirement efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (0 parameters, no output schema), the description is fairly complete. It explains what the tool does and the auth requirement. However, it does not describe the response format, which would be beneficial for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description does not need to add parameter semantics. The baseline for 0-param tools is 4, and the description is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'org credit remaining / usage'. It also mentions the specific HTTP method and endpoint. This distinguishes it from sibling tools which are all about scraping jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists a prerequisite (read_usage scope) and implies usage for checking credit usage. However, it does not explicitly state when to use vs alternatives, though the sibling tools are unrelated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_jobGet job statusA

Poll crawl, batch, or map job status by id (GET /v1/crawl/{id}, /v1/batch/scrape/{id}, or /v1/map/{id}).

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Job id returned by crawl, map, or batch_scrape
`kind`	No	Which job surface to poll. Default auto tries crawl → batch → map until one succeeds.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses polling behavior, the auto fallback logic, and endpoints. It doesn't mention rate limits, latency, or error scenarios, but overall transparency is good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the key verb and resource. No filler, every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description could do more to explain the response format (e.g., status fields). However, the title 'Get job status' and description imply what to expect. It provides sufficient context for a simple polling tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context: for 'id' it says 'Job id returned by crawl, map, or batch_scrape', and for 'kind' it explains the enum values and default auto behavior, providing value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Poll crawl, batch, or map job status by id', clearly specifying the verb (poll) and resource (job status). It distinguishes from siblings by naming specific job types (crawl, batch, map) and mentioning endpoints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains which job types it can poll and the default 'auto' behavior. It implies usage after obtaining a job id from crawl, map, or batch_scrape, but doesn't explicitly contrast with other tools or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mapMap site URLsA

Map a website's URLs via POST /v1/map. Returns a job handle; poll with get_job when async.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Site URL to map
`search`	No	Optional search filter for discovered URLs
`maxUrls`	No	Maximum URLs to discover
`noSitemap`	No	Skip sitemap.xml discovery when true
`includeSubdomains`	No	Whether to include subdomains

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the async nature and polling mechanism but lacks details on rate limits, authentication, side effects, or output format, providing minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action and key behavioral note (async polling). Every word adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 params, async pattern, no output schema), the description covers the basic lifecycle but omits details about the eventual job output or any constraints, leaving gaps for an agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 5 parameters. The tool description does not add additional meaning beyond what the schema provides, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool maps a website's URLs, specifies the POST /v1/map endpoint, and distinguishes from sibling tools like 'crawl' and 'scrape' by focusing on URL discovery rather than content extraction or deep crawling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the asynchronous workflow (returns a job handle, poll with get_job) but does not explicitly state when not to use this tool or directly compare with siblings, though the context of siblings implies differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scrapeScrape URLA

Scrape a single URL via Basecrawl SaaS POST /v1/scrape (Bearer API key). Returns Firecrawl-like document JSON. Residual anti-bot/Chromium risk remains; not a commercial unlocker and not anonymous egress.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	Absolute HTTP(S) URL to scrape
`formats`	No	Optional formats list (e.g. ["markdown","html","links","metadata"]). Engine applies a sensible default when omitted.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses behavioral traits: POST method, Bearer API key, residual anti-bot/Chromium risk, and that it is not a commercial unlocker or anonymous egress. It lacks details on rate limits or error handling but provides valuable caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, both earning their place. The first sentence defines the core action, the second adds critical behavioral disclaimers. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-URL scrape tool with no output schema, the description provides sufficient context: API method, return type (Firecrawl-like JSON), and risk warnings. However, it could be improved by mentioning error handling or response structure briefly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (url and formats). The description does not add extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'scrape', the resource 'a single URL', and the method via Basecrawl SaaS POST. It distinguishes from siblings like batch_scrape and crawl by specifying single URL. It also mentions the API key and return format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. There is no mention of when to prefer scrape over batch_scrape, crawl, or other siblings. Context signals show sibling tools but description does not address selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Jul 16, 2026
- First observedbatch_scrape
- First observedcrawl
- First observedcredit_usage
- First observedget_job
- First observedmap
- First observedscrape

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-16 19:41 across 6 tools

Disambiguation5/5

Each tool has a distinct purpose: single scrape, batch scrape, crawl, mapping, job polling, and credit checking. Descriptions clearly differentiate them, so an agent can reliably choose the right tool.

Naming Consistency5/5

All tool names use consistent lowercase underscore style, with verbs (scrape, crawl, map, get) followed by nouns where appropriate. The pattern is uniform and predictable.

Tool Count5/5

Six tools cover the essential operations for web scraping and crawling: single, batch, crawl, map, job status, and usage. This is a well-scoped set with no unnecessary tools.

Completeness4/5

Core operations are covered, but there is a potential gap in retrieving full scraped data after crawl/map jobs (get_job only polls status). Missing cancel/list job tools are minor but notable.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Crawlbase A
io.github.pipeworx-io
Crawlbase MCP — wraps the Crawlbase Crawling API (crawlbase.com, formerly
Web Scraping Browser Automation
2
FetchRelay
com.fetchrelay
Extract public webpages as Markdown, map sites, and run bounded crawl jobs. API key required.
Web Scraping Browser Automation
1
WebLens B
dev.weblens
Scrape, crawl, map and extract the web. Pay per call in USDC, no account or API key.
Web Scraping Browser Automation Research & Data
361
Spider CloudOAuth
cloud.spider
Crawl, scrape, search the web, and automate browsers at scale with anti-bot bypass.
Browser Automation Web Scraping
2

Related MCP Servers

WebScraping-AI MCP Serverofficial
Web Scraping RAG Systems
webscraping-ai
A
license
D
quality
A
maintenance
Interact with WebScraping.AI API for web data extraction and scraping
Updated 2 months ago (2026-07-24 03:26 UTC)
7
50 npm
43
MIT
Dev Tool MCP
Web Scraping Browser Automation
osins
F
license
Not graded
quality
D
maintenance
Provides web crawling and browser automation capabilities with support for multiple content formats (HTML, JSON, PDF, screenshots, Markdown), page content extraction, console message monitoring, and network request tracking.
Updated 10 months ago (2025-11-22 16:20 UTC)
-
Fetch Crawl MCP
Browser Automation Web Scraping
GeorgesAdSim
F
license
A
quality
D
maintenance
Enables fetching, crawling, and analyzing web pages with 29 tools for SEO audits, content extraction, and more.
Updated 5 months ago (2026-05-11 15:24 UTC)
29
-
Vercel MCP Web Crawler
Browser Automation Web Scraping
AIEterprise
A
license
Not graded
quality
B
maintenance
Provides lightweight web crawling and scraping capabilities, enabling users to fetch pages as clean Markdown, recursively crawl domains, extract metadata, and perform search-and-crawl operations.
Updated a month ago (2026-08-13 11:51 UTC)
2 npm
MIT

Basecrawl MCP

Requirements

Install

Configuration

Run (stdio)

Claude Desktop

Cursor

Smoke against local API

Tests

Honesty

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

WebScraping-AI MCP Serverofficial