MCP server

The Consuela MCP server exposes 16 tools over the Model Context Protocol, giving AI assistants direct access to crawl sessions, page-level findings, redirect analysis, and on-demand crawls. It reads from the same SQLite database the desktop app writes, so any session you have already recorded is available immediately.

Setup

The MCP server supports two transports. Stdio runs the consuela-mcp binary directly — most desktop clients, including Claude Desktop, use this mode. Streamable HTTP connects to the API server at POST /mcp, useful when the crawler runs on a remote host or inside the hosted tier.

Stdio transport

Point CONSUELA_DB at a crawl database and start the binary:

CONSUELA_DB=/path/to/crawls.db consuela-mcp

To register it with Claude Desktop in one step:

claude mcp add consuela /path/to/consuela-mcp

Streamable HTTP transport

When the API server is running, the MCP endpoint is available at POST /mcp. If the server requires authentication, set CONSUELA_MCP_TOKEN in the client's environment to pass a bearer token with each request.

Session tools

Session tools list and inspect the crawl sessions stored in the database. Every crawl — whether started from the desktop app, the CLI, or the crawl_site tool below — creates a session.

Tool	Parameters	Description
`list_sessions`	none	Return every crawl session in the database with its URL, page count, and timestamp.
`get_session_stats`	`session_id`: integer	Aggregate statistics for a single session — status code distribution, issue counts by severity, and response time percentiles.
`get_aggregate_stats`	none	Combined statistics across all sessions in the database.
`delete_session`	`session_id`: integer	Remove a session and all of its page records from the database.

Tool	Parameters	Description
`query_pages`	`session_id`: integer `status_code`: integer (optional) `status_min`: integer (optional) `status_max`: integer (optional) `url_contains`: string (optional) `limit`: integer (optional, default 50, max 200) `offset`: integer (optional)	Search pages in a session. Filter by exact status code, status range, or URL substring. Results are paginated.
`get_page`	`page_id`: integer	Full record for a single page — URL, status, headers, title, meta description, issues, and timing.
`get_broken_links`	`session_id`: integer	Every link that resolved to a 4xx or 5xx status, with the source page that linked to it.
`get_inbound_links`	`session_id`: integer `url`: string	All internal pages that link to the given URL within the session.
`get_images_missing_alt`	`session_id`: integer	Images found without alt text, grouped by the page they appear on.

Analysis tools

Analysis tools run higher-level inspections over an entire session — redirect health, chain depth, and headless-rendering diagnostics.

Tool	Parameters	Description
`get_redirect_summary`	`session_id`: integer	Counts of 301, 302, 307, and 308 redirects in the session, with the most-redirected target URLs.
`get_pages_with_redirect_issues`	`session_id`: integer	Pages whose redirect behaviour needs attention — temporary redirects on permanent-looking paths, redirect loops, and mixed-protocol hops.
`get_pages_with_long_chains`	`session_id`: integer	Pages that pass through three or more redirects before reaching a final destination.
`get_headless_summary`	`session_id`: integer	Results from the headless renderer — JavaScript-dependent content, client-rendered differences, and pages that timed out during rendering.

Crawl tools

Crawl tools let an AI assistant start a crawl directly, without switching to the desktop app or CLI. Single-page fetches return results inline; full site crawls persist to the database as a new session.

Tool	Parameters	Description
`crawl_url`	`url`: string	Fetch a single URL and return its status, headers, title, and issues. Results are not persisted to the database.
`crawl_site`	`url`: string `max_depth`: integer (optional, default 3) `max_urls`: integer (optional, default 50, max 500) `concurrency`: integer (optional, default 5) `requests_per_second`: float (optional, default 2.0) `respect_robots_txt`: boolean (optional, default true)	Crawl a site from the given start URL and store the results as a new session. Respects robots.txt by default. You are responsible for not overloading a server — keep concurrency and rate limits reasonable.

Host tools

Host tools inspect the system's host-file configuration, which can affect how crawled URLs resolve.

Tool	Parameters	Description
`read_hosts_file`	none	Return the current contents of the system hosts file.
`list_hosts_versions`	none	Show the version history of saved hosts-file snapshots, if any have been recorded.