Local API and MCP server

Crawlune Pro exposes the running app over HTTP on your own machine, so scripts can start crawls and read every result, and AI assistants can use Crawlune as a tool through the Model Context Protocol. Nothing leaves your computer: the listener binds to 127.0.0.1 only and every request carries a token the app generated.

1. Turn it on

In Crawlune, open Settings → Integrations → Local API and MCP server and tick Enable the local API. The status next to it reads Listening.
Copy the token. The default port is 7420; change it there if something else uses it.
Try it:

curl -H "Authorization: Bearer YOUR_TOKEN" http://127.0.0.1:7420/v1/status

The API answers JSON. Errors look like {"error": "busy", "message": "…"} with a matching HTTP status (401 wrong token, 403 feature needs Pro, 404, 409 conflict).

2. Run a crawl from a script

API=http://127.0.0.1:7420/v1
AUTH="Authorization: Bearer YOUR_TOKEN"

curl -s -H "$AUTH" -H "content-type: application/json" \
  -d '{"url": "https://example.com", "maxUrls": 500}' $API/crawl

# poll until the state is "finished"
curl -s -H "$AUTH" $API/status | jq .crawl.state

# then read the results
curl -s -H "$AUTH" "$API/issues" | jq '.issues[] | [.id, .count]'
curl -s -H "$AUTH" "$API/pages?issue=title_missing&limit=50" | jq '.pages[].url'
curl -s -H "$AUTH" "$API/plan" | jq '.actions[:5]'

One crawl runs at a time, the same one you see in the window. Finished crawls land in the library like any other, so the saved-crawl routes, comparisons and trends all apply.

3. Routes

Route	What it does
GET /v1	Route index and app version.
GET /v1/status	Crawl state and progress; once pages exist, the overview (totals, status codes, indexability, errors, warnings, opportunities, health).
POST /v1/crawl	Start a crawl. Body is a crawl config in JSON: startUrl (or url), maxUrls, maxDepth, mode (spider \| sitemap), jsRender, includeSubdomains, crawlResources and any other setting the app has. Returns 202, or 409 while a crawl runs.
POST /v1/crawl/stop · /pause · /resume	Control the running crawl.
GET /v1/issues?category=	Checks with findings: id, category, severity, title, why, fix, count.
GET /v1/issues/{check}?limit=&offset=	One check and its affected pages (also answers for checks with no findings).
GET /v1/pages?issue=&search=&url=&internal=&kind=&status=&limit=&offset=	Crawled URLs with every column. status takes 2xx, 3xx, 4xx, 5xx, none or a code; kind is html, image, css, script, pdf or other; url matches one page ignoring scheme, www and the trailing slash. limit defaults to 100, at most 5,000.
GET /v1/pages/{id}	Everything about one page: fields, headings, links in and out, images, hreflang, structured data, issues, integration metrics.
GET /v1/pages/{id}/html?rendered=1	Stored HTML source, or the rendered DOM when the crawl rendered JavaScript.
GET /v1/plan	The action plan: issues ranked by health points recovered and link equity, with effort and the most-linked affected URLs.
GET /v1/checks?category= · /v1/checks/{check}	The catalogue of checks with their explanations.
GET /v1/library	Saved crawls.
POST /v1/library/save	Save the current crawl; body {"name": "…"} is optional.
POST /v1/library/{id}/open	Load a saved crawl into the workspace.

Page rows and details use the same field names as the app's CSV export (camelCase). Send the token either as a bearer header or as ?token=.

4. MCP server for AI assistants

The app binary doubles as an MCP server over stdio. Claude Desktop, Claude Code, Cursor and any other MCP client can run crawls and ask questions about the results. The server talks to the running app's local API, so keep Crawlune open with the API enabled.

Settings → Integrations shows the exact snippet for your installation with the copy button. It looks like this on macOS:

{
  "mcpServers": {
    "crawlune": {
      "command": "/Applications/Crawlune.app/Contents/MacOS/crawlune",
      "args": ["mcp"]
    }
  }
}

Claude Desktop: Settings → Developer → Edit config, add the entry to claude_desktop_config.json, restart Claude.
Claude Code: claude mcp add crawlune -- "/Applications/Crawlune.app/Contents/MacOS/crawlune" mcp
Cursor: Settings → MCP → Add new server, paste the same JSON.
Windows: the command is C:\Program Files\Crawlune\crawlune.exe; Linux: the AppImage path or /usr/bin/crawlune.

Then ask things like "Crawl example.com and tell me the three fixes with the biggest impact", "Which pages are missing a meta description?" or "What does the canonical_mismatch check mean?".

Tools

Tool	Arguments
start_crawl	url, max_urls, max_depth, include_subdomains, js_render, mode, crawl_resources
wait_for_crawl	timeout_seconds
crawl_status	—
stop_crawl	—
list_issues	category
issue_pages	check, limit, offset
list_pages	search, check, status, kind, internal, limit, offset
page_details	id or url
page_html	id, rendered
action_plan	—
explain_check	check
list_checks	category
list_saved_crawls	—
open_saved_crawl	id
save_crawl	name

5. Headless on a server

The same API runs without a window: crawlune serve --port 7420 starts it on a machine where the Pro licence is activated (activate with the app once, or crawlune licence shows the state). Crawls started this way are saved to that machine's library. To point an MCP client at it, set CRAWLUNE_API_URL and CRAWLUNE_API_TOKEN in the client's environment; the listener still accepts local connections only, so tunnel with SSH for remote use.

Security

The listener binds to 127.0.0.1; it is not reachable from the network.
Every request needs the token. Regenerate it in Settings if it leaks; the old one stops working at once.
There is no CORS header, so web pages open in your browser cannot call the API.
Turn the API off when you do not need it; it is off by default.