---
title: "CrawlRaven MCP server reference"
description: "OAuth, tools, access modes, limits, prompts, errors, and security boundaries for the CrawlRaven MCP server."
canonical: "https://crawlraven.com/docs/mcp"
markdown: "https://crawlraven.com/docs/mcp.md"
product: "CrawlRaven v2"
last_verified: "2026-08-19"
---

# CrawlRaven MCP server reference

> Remote, OAuth-protected, read-only access to approved CrawlRaven data for compatible AI clients.

## Connection

- **Endpoint:** `https://mcp.crawlraven.com/mcp`
- **Transport:** Remote Streamable HTTP
- **Authorization:** OAuth authorization code with S256 PKCE
- **Access token:** 1 hour
- **Grant, refresh token, and DCR registration expiry:** 90 days
- **First call:** Use `list_websites`, then pass its `website_id` to site-specific tools.
- **Secrets:** Do not paste Google tokens, browser cookies, personal access tokens, or client secrets into prompts or client configuration.

## Access modes

| Mode | Websites | Search period | List rows | Pagination | Tools | Daily allowance |
| --- | --- | --- | --- | --- | --- | --- |
| Eligible free preview | One account-pinned activated website | Fixed 28 days | Up to 50 | No | Seven; no annotations | 20 tool calls shared per account, resetting at 00:00 UTC |
| Full access | Eligible websites in the selected paid account | 7, 28, 90, or 365 days | Up to 100; annotations up to 200 | Cursor pagination where documented | All eight | Not subject to the free-preview daily allowance |

A free grant does not widen after an upgrade. Reconnect and approve a full grant. Reconnecting a free grant does not switch its pinned website.

## Tools

| Tool | Scope | Parameters | Returns |
| --- | --- | --- | --- |
| list_websites | websites:read | None | Website IDs, names, lifecycle, activation, and access state. |
| get_website_overview | search_performance:read | website_id, days | Current and previous KPI totals plus the actual reporting period. |
| get_search_performance | search_performance:read | website_id, days | Daily rows, KPI comparison, period, and attribution state. |
| list_queries | search_performance:read | website_id, days, search, limit, cursor | Bounded Query rows and pagination state. |
| list_pages | search_performance:read | website_id, days, search, limit, cursor | Bounded Page rows and pagination state. |
| list_opportunities | opportunities:read | website_id, status, limit, cursor | Persisted opportunities, Priority, evidence, and actions. |
| list_target_keywords | targets:read | website_id, status, search, limit, cursor | Durable target plans; no live mismatch evidence. |
| list_annotations | annotations:read | website_id, days, limit, cursor | Notes, Google updates, and opportunity timeline events. |

## Important response boundaries

- Query and Page results come from bounded Search Console dimensional corpora and may omit anonymized or lower-traffic rows.
- A missing row is unknown, not proof of zero impressions.
- Search Console MCP periods are 7, 28, 90, or 365 days; the app-only 16-month view is not an MCP parameter.
- Opportunity reads use persisted findings; MCP cannot refresh or change their lifecycle.
- Target Keyword reads contain the durable plan, not live observed-page or mismatch evidence.
- There is no standalone GA4 reporting tool. Opportunity rows may contain already attached page-level outcome evidence.
- MCP cannot write data, run exports, access billing, fetch arbitrary URLs, call webhooks, send email, or use undocumented REST routes.

## Pagination

Full-access Query, Page, Opportunity, and Target Keyword lists default to 25 rows and accept up to 100. Annotations default to 100 and accept up to 200. Pass `next_cursor` back as `cursor` without changing the tool, website, period, search, or status. Stop when `next_cursor` is empty. Always report truncation separately from pagination completion.

## Prompt template

Replace `[your site]` with the exact CrawlRaven site name or domain before pasting. Free-preview prompts that say “my pinned site” require no replacement.

## Prompts by role

### Founder / owner

A concise decision brief without SEO jargon. Start with the preview-safe prompt; use the second when timeline access is available.

- **Preview + full:** Use my CrawlRaven site. Summarize the last 28 days against the preceding period, name the three current opportunities that matter most, and give me one concrete next action for each. Keep it to ten bullets and state any data limits.
- **Full access:** Prepare my 90-day owner brief for [your site]: headline search movement, the pages that lost the most clicks in the returned corpus, the three highest-priority current opportunities, and any nearby timeline event worth investigating. Do not claim that timing proves causation.

### SEO specialist

Diagnosis with explicit periods, bounded rows, and evidence behind each recommendation.

- **Free preview:** For my pinned site, find returned queries with meaningful impressions and average position between 4 and 20 over the available 28-day period. Compare them with current striking-distance opportunities and rank the best five actions by Priority.
- **Full access:** For [your site], inspect the 90-day query corpus page by page until next_cursor is empty. Find high-impression returned queries in positions 4–20, compare them with current opportunities and target keywords, and state how many rows you inspected and whether the source was truncated.

### Agency / consultant

Client-ready reporting that keeps the site, period, comparison, and evidence boundary attached.

- **Free preview:** Create a client-safe 28-day search update for my pinned site: headline KPI movement, the five returned Query and Page movers, and the top three current opportunities. Separate observations from recommendations and include the report scope.
- **Full access:** Write the monthly search update for [your site] using the last 90 days: KPI comparison, leading returned Query and Page gains and losses, current opportunity priorities, and relevant notes or Google updates from the timeline. End with three next actions and a data-boundary note.

### Content lead / editor

Turn current search evidence and the durable target plan into an editorial queue.

- **Preview + full:** For my pinned site, combine the five highest-priority current opportunities with targeted keywords that have no planned URL. Produce a short editorial queue with the evidence and recommended action for each item.
- **Full access:** For [your site], find current content-decay opportunities, inspect the affected pages' returned 90-day search performance, and compare them with the durable target plan. Produce an editorial brief for the best five candidates and identify where the evidence is only partial.

### Developer / analyst

Structured, reproducible output without inventing unsupported REST endpoints or write operations.

- **Preview + full:** Return a JSON object for my pinned site with its website_id, lifecycle and access state, the 28-day KPI values and deltas, and the request scope used. Do not call tools that are not needed for those fields.
- **Full access:** For [your site], retrieve the 365-day daily Search Console series and the complete available 90-day Page result set using next_cursor. Return JSON with the reporting periods, rows inspected, truncation state, and whether cursor pagination completed. Do not fetch URLs or use undocumented API routes.

### Just exploring

Learn what the account contains before asking for a deeper analysis.

- **Preview + full:** Show which CrawlRaven websites I can use, explain which one is available to this connection, and suggest three useful read-only questions I can ask next without exceeding my access mode.

## Error recovery

- **401:** Let the client refresh its token; reconnect if the grant is expired or revoked.
- **403 / forbidden:** Confirm account eligibility, website access, and approved scopes.
- **rate_limited:** Wait for the supplied retry interval. Free preview resets its shared allowance at 00:00 UTC.
- **validation_failed:** Recheck parameters. A cursor must be reused with the exact scope that created it.
- **Request ID:** Include an error's request ID when contacting support; never include credentials.

## Related guides

- [Connect an AI client with MCP](https://crawlraven.com/docs/mcp-connections) ([Markdown](https://crawlraven.com/docs/mcp-connections.md))
- [Use the free MCP preview](https://crawlraven.com/docs/mcp-free-preview) ([Markdown](https://crawlraven.com/docs/mcp-free-preview.md))
- [Use MCP with full access](https://crawlraven.com/docs/mcp-full-access) ([Markdown](https://crawlraven.com/docs/mcp-full-access.md))