⌘K

Docs / MCP server reference

CrawlRaven MCP server

Free preview + paidVerified October 2026

A remote Model Context Protocol server that exposes approved CrawlRaven data to an AI client through typed, scoped tools and OAuth. Eligible free previews have 9 bounded tools for one website that only read data. Paid connections can expose up to 30 tools, including Technical SEO audits, imported Generative AI reports, linked GA4 reporting, and optional write permissions you approve separately. New to this? The connection guide covers the in-app consent and revocation workflow.

Looking for help with the app itself? Start with the CrawlRaven product guides.

Server URL

https://mcp.crawlraven.com/mcp

Overview

Add the server URL to a client that supports remote MCP over OAuth, approve the connection in the browser, and the CrawlRaven tools appear in that client. There is nothing to install and no key to paste.

Tools return structured rows with a short text summary. Ask about declining queries, weekly priorities, Google updates near a traffic drop, linked GA4 landing-page outcomes, new Technical SEO findings, or whether keywords rank on their intended pages.

Property	Value
Endpoint
Transport	Remote HTTP (Streamable HTTP)
Authentication	OAuth authorization code with S256 PKCE
Tools	9 in free preview; up to 30 with paid access
Scopes	4 in free preview; up to 11 with paid access
Side effects	None unless a paid connection approves a write permission: direct changes to opportunity status, target keywords, or manual notes, or proposed note changes you approve in CrawlRaven

Availability

Paid MCP access is included with paid plans

A paid allowance from an active subscription, lifetime plan, or support override enables the paid catalog. The tools a client sees still depend on the scopes that user explicitly approved. Eligible free accounts can use the bounded preview while the experiment is enabled for them.

Access mode	What it includes
Free preview	9 tools for one activated website: Search Console reports, opportunities, the prioritized SEO plan, target keywords, and target-to-page alignment. Fixed 28-day reporting; up to 50 rows; no pagination, annotations, Analytics, Technical SEO, Generative AI, or writes; 20 tool calls shared by the account each UTC day.
Paid read access	Read tools for Search Console, imported Generative AI snapshots, opportunities and the prioritized plan, target keywords, page and target alignment, and active annotations, with supported reporting windows and bounded cursor pagination.
+ View analytics	Two paid-only tools for bounded reports from the GA4 property already linked to the website.
+ View Technical SEO audits	Four paid-only tools to read stored audits, findings, and comparisons. They cannot start an audit.
+ Direct write permissions	Manage opportunity status adds one tool, Manage target keywords adds two, and Manage manual notes directly adds four plus the archived-note list. These change data without further approval.
+ Propose annotation changes	Two paid-only tools to plan and track manual note changes that the same user approves in CrawlRaven, plus the archived-note list. With every approved scope, the catalog has 30 tools.

Free preview is account-specific, not a promise for every free account. Its first approved grant pins the account to one activated website; later free grants cannot choose another. Upgrading does not widen an existing free grant’s scopes or remove its website pin. Reconnect after upgrading to review paid access. Existing paid grants also keep their original scopes: reconnect and explicitly approve any newly available permission, such as View Technical SEO audits or a write permission, to add those tools.

Eligibility is checked on every tool call. If paid access lapses, a paid grant stays visible and revocable but returns no data until paid access is restored. If a free preview becomes unavailable, its grant likewise remains visible and revocable.

See Billing for current plan availability, or the changelog for what shipped when.

Quickstart

01
Add the server URL
In the MCP or connector settings of an OAuth-capable client, add as the server.
02
Sign in to CrawlRaven
The client opens a browser prompt. Sign in with the account that owns the websites you want the agent to see.
03
Review the consent screen
Check the client name, choose an eligible CrawlRaven account, and read every requested permission. The consent screen separates direct changes, changes you approve, and read access. Analytics, Technical SEO audits, and each write permission are separate paid permissions. A free preview also asks for its pinned website. One grant covers one client, one user, and one account.
04
Approve and return to the client
Let the browser tab finish its redirect. Closing it early leaves the token exchange incomplete, which is the usual reason no tools appear.
05
Call list_websites
It returns the website_id every other tool needs.

Client setup

Claude.ai and Claude Desktop

Customize > Connectors > add a custom connector, then paste the server URL.

Server URL

https://mcp.crawlraven.com/mcp

Claude Code

Add the server, then authenticate from /mcp or with claude mcp login crawlraven.

Terminal

claude mcp add --transport http crawlraven https://mcp.crawlraven.com/mcp

ChatGPT

Enable developer mode, add a custom connector with the server URL, complete the OAuth prompt.

Server URL

https://mcp.crawlraven.com/mcp

Codex

Add the Streamable HTTP server URL, then sign in from the CLI.

Terminal

codex mcp login crawlraven

OpenClaw

Add the server with OAuth, then log in.

Terminal

openclaw mcp add crawlraven --url https://mcp.crawlraven.com/mcp \
  --transport streamable-http --auth oauth
openclaw mcp login crawlraven

Cursor

Add a remote Streamable HTTP MCP server with the CrawlRaven URL, choose OAuth when prompted.

Server URL

https://mcp.crawlraven.com/mcp

Authorization

CrawlRaven supports the standard client registration order and falls back down it: a pre-registered client ID, currently used only by MCP Inspector, then Client ID Metadata Documents, which clients such as ChatGPT prefer, then RFC 7591 Dynamic Client Registration.

Item	Behavior
Flow	Authorization code with S256 PKCE on all three registration paths
Consent	Per client, user, and account; requested again for a different account
Access token	One hour
Refresh token	Rotates after each successful renewal
Expiry	Refresh tokens, DCR registrations and grants all expire after 90 days
Callbacks	HTTPS redirect URIs must match exactly. Native clients may use an HTTP loopback callback, where only the port may vary. Cursor may use its exact application-owned callback; other private-use schemes are rejected.

Do not paste secrets

The client performs OAuth discovery on its own. A CrawlRaven personal access token, a Google token, browser cookie, or annotation approval credential does not belong in a client configuration. Annotation approval opens in CrawlRaven through a one-time browser handoff; the approval credential is never returned to the client.

Tools

30 tools are available across all paid permissions. A client only sees tools covered by its approved scopes, and a tool that names a second scope needs both. Free preview grants receive the 9 rows marked Paid + preview; Analytics, Technical SEO, Generative AI, annotation, and write tools are unavailable in preview.

Tool	Access	Scope	Returns	Parameters
`list_site_audits`	Paid + View Technical SEO audits	technical_seo:read	Lists stored Technical SEO audits for one website, newest first. It does not start audits; an empty list means no retained audits, not a clean website.	website_id, limit, cursor
`get_site_audit`	Paid + View Technical SEO audits	technical_seo:read	Returns one stored audit's state, coverage, caveats, and paginated rule summaries with observations, why it matters, and suggested fixes.	website_id, run_id, limit, cursor
`list_site_audit_findings`	Paid + View Technical SEO audits	technical_seo:read	Lists stored findings with exact affected or source URLs and evidence, including broken-link destinations and status codes when available.	website_id, run_id; rule, severity, category, url, change; limit, cursor
`compare_site_audits`	Paid + View Technical SEO audits	technical_seo:read	Compares two finished audits of the same website by rule and URL. Partial coverage can make a finding look fixed when it was not rechecked.	website_id, run_id; baseline_run_id; limit, cursor
`list_websites`	Paid + preview	websites:read	Lists authorized websites, up to 100, with lifecycle, access, and monitoring metadata.	None
`get_website_overview`	Paid + preview	search_performance:read	Returns headline Search Console KPIs and comparison deltas for one authorized website.	website_id; days or start + end
`get_search_performance`	Paid + preview	search_performance:read	Returns daily Search Console rows for trend analysis, plus totals and a previous-period comparison.	website_id; days or start + end
`list_queries`	Paid + preview	search_performance:read	Returns a bounded Search Console Query corpus with optional query text or exact-page filtering.	website_id; days or start + end; search, page; limit, cursor
`list_pages`	Paid + preview	search_performance:read	Returns a bounded Search Console Page corpus with metrics, optional page text filtering, trend filtering, and sitemap page dates.	website_id; days or start + end; search, trend, updated_before, date_status; limit, cursor
`get_analytics_summary`	Paid + View analytics	analytics:read	Returns linked GA4 totals and comparison deltas for a bounded complete-day period.	website_id; days or start + end; landing_page, landing_page_match, source_medium, source_medium_match, country, device
`get_analytics_breakdown`	Paid + View analytics	analytics:read	Returns a bounded linked GA4 breakdown by content group, landing page, source/medium, country, or device.	website_id; dimension; days or start + end; filters; limit
`list_opportunities`	Paid + preview	opportunities:read	Returns current actionable opportunities with priority, evidence, impact, and recommendation context.	website_id, status, limit, cursor
`get_prioritized_seo_plan`	Paid + preview	opportunities:read	Ranks open opportunities by the website's saved SEO priorities and explains each signal's evidence, weight, points, and rank change. Request-only adjustments are never saved.	website_id, limit; request-only overrides: preset, weights, outcome_first, strategic_keywords, keyword_priorities, page_priorities, key_events, value_source, estimated_values, brand_preference_mode, page_types, compare_with_saved
`get_page_query_mapping`	Paid; also needs targets:read	search_performance:read	Starts from one page URL and compares its bounded query corpus with saved target keywords, reporting whether each query is planned for this page, another page, or no page.	website_id, page_url; days or start + end; ownership, search, limit, cursor
`get_target_page_alignment`	Paid + preview; also needs search_performance:read	targets:read	Compares each target keyword's intended page with the page leading in Search Console clicks, and reports unassigned targets. Capped evidence never proves absence or mismatch.	website_id; status, search, assignment, alignment; days or start + end; limit, cursor
`list_target_keywords`	Paid + preview	targets:read	Returns the durable target-keyword plan: planned URLs, intent groups, priority, and status. Observed pages and mismatches come from get_target_page_alignment.	website_id, status, search, limit, cursor
`list_generative_ai_imports`	Paid only	search_performance:read	Lists manually imported Search Console Generative AI export snapshots with their Pacific Time periods, filters, and provenance. Snapshots are never combined.	website_id, limit, cursor
`get_generative_ai_pages`	Paid only	search_performance:read	Returns page impressions for one imported snapshot's full period. Missing pages are unknown, not zero, and there are no query, click, or daily page values.	website_id, import_id; start + end; limit, cursor
`get_generative_ai_trend`	Paid only	search_performance:read	Returns daily chart impressions for one imported snapshot, in Pacific Time. A requested subset must be fully covered by the export.	website_id, import_id; start + end
`list_annotations`	Paid + View annotations	annotations:read	Returns active manual notes, verified Google updates, and imported events from the website timeline.	website_id, days, limit, cursor
`create_target_keyword`	Paid + Manage target keywords	targets:write	Adds one manual target keyword with an optional intended page and priority. An existing keyword returns conflict and stays unchanged.	website_id, keyword; target_url, priority
`update_target_keyword`	Paid + Manage target keywords	targets:write	Assigns the intended page or changes the priority of one target keyword. Omitted fields stay unchanged and null clears a field.	website_id, target_id; target_url, priority
`update_opportunity_status`	Paid + Manage opportunity status	opportunities:write	Resolves, ignores, snoozes, or reopens one opportunity. Snooze defaults to seven days; repeated or invalid transitions return conflict.	website_id, opportunity_id, action; snooze_until
`create_annotation`	Paid + Manage manual notes directly	notes:write	Creates one manual website note without further approval. Retries with the same idempotency key return the original note.	website_id, idempotency_key, date, title; date_end, detail, category
`update_annotation`	Paid + Manage manual notes directly	notes:write	Updates one manual note without further approval. A stale version returns conflict instead of overwriting newer work.	website_id, annotation_id, expected_version, changes
`archive_annotation`	Paid + Manage manual notes directly	notes:write	Archives one manual note without further approval. Archiving is reversible; MCP cannot permanently delete notes.	website_id, annotation_id, expected_version
`restore_annotation`	Paid + Manage manual notes directly	notes:write	Restores one archived manual note without further approval, checked against its current version.	website_id, annotation_id, expected_version
`plan_annotation_change`	Paid + Propose annotation changes	annotations:write	Plans a create, update, archive, or restore of a manual annotation and returns a short-lived approval URL; planning alone changes nothing.	website_id, action, idempotency_key; create/update fields; annotation_id and expected_version when required
`get_annotation_change_status`	Paid + Propose annotation changes	annotations:write	Returns the status and, when available, the result of an annotation change plan without repeating the mutation.	plan_id
`list_archived_annotations`	Paid + either note permission	annotations:write or notes:write	Lists archived manual annotations and their current versions for review or version-checked restore.	website_id, limit, cursor

Parameters

Name	Type	Notes
`website_id`	string, required	The website to query. Every tool except list_websites and get_annotation_change_status needs one.
`days`	number, default 28	Rolling reporting window. Paid Search Console and Analytics tools accept 1 through 365; list_annotations accepts 1 through 400. Do not combine days with start/end.
`start / end`	YYYY-MM-DD pair, optional	Paid-only inclusive dates spanning at most 365 days. Supply both or neither. Supported by Search Console overview, performance, Query and Page tools, plus both Analytics tools.
`dimension`	enum, Analytics breakdown only	One of content_group, landing_page, source_medium, country, or device.
`Analytics filters`	strings, optional	Filter landing_page or source_medium by exact or case-insensitive contains, and country or device by exact value.
`page`	absolute HTTP(S) URL, optional	Paid-only exact page filter for list_queries. May be combined with search, which continues to filter query text.
`search`	string, optional	Case-insensitive substring filter, up to 500 characters. Applies to query keys, page keys or target keywords.
`status`	enum, optional	Opportunities: active, in_progress, resolved, returned, ignored, snoozed, all. Omitted returns active and returned. Target keywords and target alignment: targeted or ignored.
`limit`	number, default 25	Rows per page, usually capped at 100. list_annotations defaults to 100 and caps at 200; Analytics breakdown defaults to 25 and caps at 100.
`cursor`	string, optional	The next_cursor from the previous page. Search, plan, and annotation list cursors remain bound to their original filter scope.
`action + idempotency_key`	enum + UUID, annotation planning	plan_annotation_change takes create, update, archive, or restore with a stable UUID for safe retries; create_annotation also takes an idempotency_key. Reusing a key with different content is rejected.
`annotation_id + expected_version`	UUID + positive integer	Required for update, archive, and restore, whether planned or direct. A stale version conflicts instead of overwriting a newer change.
`run_id / baseline_run_id`	UUID, Technical SEO tools	An audit ID from list_site_audits. compare_site_audits compares run_id with baseline_run_id, which must be an earlier finished audit; omit it to use the previous finished audit.
`rule, severity, category, url, change`	filters, list_site_audit_findings	Narrow stored findings by rule, severity, category, or exact affected page URL. change is new or fixed against the previous finished audit; fixed also includes findings on pages that were not rechecked.
`trend, updated_before, date_status`	filters, paid list_pages	trend keeps growing, declining, new, or lost pages across the compared periods. updated_before keeps pages whose sitemap date is before a YYYY-MM-DD cutoff; date_status keeps dated, undated, not_in_sitemap, or unknown pages.
`page_url + ownership`	URL + states, get_page_query_mapping	The page to inspect, and optional planned-ownership states to keep: aligned, belongs_elsewhere, unassigned, untracked, or ambiguous.
`assignment / alignment`	filters, get_target_page_alignment	assignment is assigned or unassigned. alignment keeps aligned, mismatched_leading_page, no_observed_ranking, or unknown targets. The leading page has the most clicks, then impressions.
`Priority overrides`	optional, get_prioritized_seo_plan	preset, weights, and the other override fields adjust the ranking for this request only and are never saved. Omit them to use the website's saved SEO priorities.
`import_id`	UUID, Generative AI tools	One snapshot from list_generative_ai_imports. Snapshots are never combined, and dates use Pacific Time.
`opportunity_id + action`	UUID + enum, update_opportunity_status	An ID from list_opportunities and resolve, ignore, snooze, or reopen. snooze_until is an optional future date; snooze defaults to seven days.
`keyword, target_id, target_url, priority`	target keyword writes	create_target_keyword takes a keyword; update_target_keyword takes a target_id from list_target_keywords. target_url and priority are optional, and null clears them on update.
`plan_id`	UUID, status lookup	The identifier returned by plan_annotation_change. Status is pending_approval, applied, denied, conflict, expired, or cancelled; pending plans also report awaiting_handoff or reviewing.

Free preview fixes days at 28, caps list results at 50, and removes start, end, page, andcursor. Full-access validation follows the parameter table above. Free preview never exposes Analytics, Technical SEO, Generative AI, page-query mapping, annotations, or any write tool.

Exact dates remain exact

CrawlRaven does not silently shift a requested custom period to fit Google's finalized or retained data. Search Console results report their returned period and partial-evidence state. Analytics uses complete UTC days ending no later than yesterday and returns the exact period, preceding comparison, provider, and truncation state. The Opportunity, prioritized plan, and Target Keyword lists do not accept report dates; target alignment and page-query mapping do.

Example prompts

You never call a tool yourself. You ask in plain language and the client picks the tool, fills in the parameters, and pages through results if it needs to. These are prompts that reliably land on each tool, so they double as a map of what the connection is good for.

Replace the site placeholder

Replace [your site] with the exact CrawlRaven site name or domain before pasting. Everything except list_websitesneeds a website, so naming it avoids an extra discovery call. Timeline prompts require View annotations; GA4 prompts require View analytics; audit prompts require View Technical SEO audits; change prompts require the matching write permission. None of those permissions are available in free preview.

list_websites

Anything that starts with which site. The agent needs a website_id before it can call anything else, so this usually runs on its own the first time.

Which websites do I have in CrawlRaven?
Which of my sites are activated, and which have full workspace access?
Use [your site] for everything I ask next.

get_website_overview

The headline number. One call, one period, and the same period before it.

How did [your site] do in search over the last 28 days?
Are clicks on [your site] up or down against the previous period, and did position move with them?
Give me a two-sentence search summary for [your site] over the last 90 days.

get_search_performance

Anything about shape over time. This returns a row per day, so the agent can find the week something changed.

Walk through daily clicks for [your site] over the last 90 days and point out the sharpest drops.
Did traffic to [your site] fall gradually or overnight?
Which week in the last year was the worst for impressions on [your site]?

list_queries

Questions about what people searched. Filterable by text, so you can scope it to a topic.

What are the top queries for [your site] over the last 28 days?
Which queries containing pricing get impressions but almost no clicks?
Compare the top queries for the last 28 days with the last 90 and tell me what is new.
For [your site], list the queries attributed to exactly [page URL] from [start date] through [end date]. State the period, rows inspected, truncation, and whether pagination completed.

list_pages

Questions about which URLs earn the traffic, and which are stuck just off the first page.

Which pages on [your site] get the most clicks this month?
Find pages with real impressions sitting between position 8 and 20.
Which of my blog posts lost the most clicks against the previous period?

get_analytics_summary · get_analytics_breakdown

Paid questions about visits and outcomes from the GA4 property already linked to the website. Use the summary for totals and trend; use the breakdown to rank one dimension.

Compare organic sessions and key events for [your site] over the last 28 complete days with the preceding period.
Break down the last 90 complete days by landing page and show which returned rows combine meaningful sessions with weak key-event rates.
For [your site], compare source/medium performance between [start date] and [end date], state that the provider is GA4, and report any truncation.

list_opportunities

The what should I do question. Opportunities already carry impact estimates, evidence and a recommended action, so the agent is reading a decision rather than inventing one.

What should I work on this week for [your site]?
Show the highest-impact active opportunities and explain the evidence behind the top three.
Turn the top five opportunities into a checklist I can hand to a writer.

list_target_keywords

Questions about the plan rather than the past: what you decided to target and which URL was meant to rank.

List the target keywords for [your site] with their planned URLs.
Which target keywords are still marked as targeted but have no planned URL?
Group my target keywords by intent and show which high-priority terms are missing a planned URL.

get_prioritized_seo_plan

Ranking open opportunities by the website's saved SEO priorities, with every signal explained. Ask for a different preset to compare without saving it.

Rank the open opportunities for [your site] by our saved SEO priorities and explain why the top five rank where they do.
Rerank the same opportunities with the conversions_first preset for this request only and show which items moved.

get_target_page_alignment · get_page_query_mapping

Checking whether the page you planned for a keyword is the one earning its clicks, starting from either the target plan or one page.

Which target keywords on [your site] have an intended page that is not the page leading in Search Console clicks?
For [page URL], show which of its queries are planned for this page, planned for another page, or not planned at all.

list_site_audits · get_site_audit · list_site_audit_findings · compare_site_audits

Paid questions about stored Technical SEO audits after the connection has View Technical SEO audits. The tools read finished audits; they cannot start one.

Summarize the latest Technical SEO audit for [your site] and list the highest-severity rules with their suggested fixes.
Compare the latest audit with the previous one and list new findings, separating fixes that were not rechecked.
List the broken-link findings from the latest audit with each source page and destination status.

list_generative_ai_imports · get_generative_ai_pages · get_generative_ai_trend

Paid questions about Search Console Generative AI exports you imported into CrawlRaven. Each snapshot stands alone and uses Pacific Time dates.

List the Generative AI imports for [your site] and the period each one covers.
From the latest import, show the pages with the most Generative AI impressions and the daily trend for the same period.

list_annotations

Questions about why. View annotations access includes active manual notes, Google updates, and opportunity milestones.

What happened on [your site] over the last 90 days?
Was there a Google update near the drop in early June?
Show the timeline for the last year and line the notes up with the traffic changes.

update_opportunity_status · create_target_keyword · update_target_keyword

Paid changes to your planning workspace after the connection has Manage opportunity status or Manage target keywords. These apply directly, so confirm the target before asking.

Snooze opportunity [opportunity ID] on [your site] for seven days and confirm its new status.
Add [keyword] as a target keyword for [your site] with [page URL] as its intended page.

create_annotation · update_annotation · archive_annotation · restore_annotation

Paid manual-note changes after the connection has Manage manual notes directly. They apply without further approval and stay version-checked.

Add a manual note to [your site] on [date] titled [title] and show me the saved note.
Archive manual note [annotation ID] at version [version] and confirm that it can be restored.

plan_annotation_change · get_annotation_change_status

Paid manual-note changes after the connection has Propose annotation changes. Planning is a preview, not a write; the same user must approve the exact change in CrawlRaven.

Plan a manual note for [your site] on [date] titled [title]. Show me the proposed values and wait for my approval; do not say it was created until status confirms completion.
Plan an update to manual annotation [annotation ID] at version [version]. Change only the title to [title], then give me the approval link.
Plan an archive of manual annotation [annotation ID] at version [version]. Explain that this is reversible and wait for my approval.

list_archived_annotations

Review archived manual notes and obtain the current version before planning a restore.

List archived manual notes for [your site] and show each annotation ID and version.
Find the archived note titled [title], then plan a version-checked restore and wait for my approval.

Prompts that chain tools

The connection is more useful when one question needs several tools. The agent decides the order, so you can ask for the outcome rather than the steps.

Monthly client update

Overview for the headline, pages and queries for the movers, timeline for the explanation.

Write the monthly search update for [your site]: how the period compared with the one before, the pages and queries that moved most, and anything on the timeline that explains it.

Page refresh research

Exact page-attributed queries from CrawlRaven, then current public content from the client’s web capability. The MCP server itself does not fetch the page.

For [your site], use CrawlRaven to list every available query attributed to exactly [page URL] from [start date] through [end date], following next_cursor until empty. Then inspect the current public content at that same URL and propose page-specific refresh ideas. Separate Search Console evidence from content observations, cite the exact period, report rows inspected and truncation, and do not claim the bounded result is exhaustive.

Decay triage

Pages first, then content-decay opportunities and the timeline to separate a page problem from a broader Google change.

Find the pages on [your site] that lost the most clicks over 90 days, check for matching content-decay opportunities, and see whether a Google update lines up with the drop.

Plan coverage

The durable target plan compared with the bounded top-query corpus.

Compare my target keywords for [your site] with the top returned Search Console queries, and flag planned terms that are absent from that bounded query list.

Search-to-outcome review

Search Console identifies discovery and ranking movement; linked GA4 reports add visits and aggregate outcomes without claiming query-to-conversion attribution.

For [your site], summarize the last 28 days of Search Console movement, then use linked GA4 to compare landing-page sessions and key events for the same complete-day period. Keep query evidence separate from page-level Analytics outcomes.

Record an approved change

Evidence first, then a proposed manual timeline note. The mutation remains pending until the same user reviews it in CrawlRaven.

Review [your site] around [date]. If the evidence supports recording [event], plan a concise manual annotation but do not apply or claim the change until I approve it in CrawlRaven.

Sprint planning

Opportunities ranked by impact, sized against the traffic the affected pages already earn.

Give me the current opportunities for [your site] ordered by impact, and for each one tell me what the affected page currently earns so I can judge whether it is worth it.

Every prompt that contains [your site] is a template. Replace it with the exact site name or domain before pasting. If the client cannot match it, it will call list_websites and ask which site you meant.

Prompts by role

Start with the job you are doing rather than a tool name. The badge under each prompt shows the minimum access it expects. Free prompts use the pinned website, fixed 28-day period, first result page, and shared daily allowance; full-access prompts can use broader periods and pagination. Prompts involving GA4 or manual note changes say which additional permission they expect.

Founder / owner

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

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.Preview + full
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.Full access

SEO specialist

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

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.Free preview
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.Full access
For [your site], compare the latest finished Technical SEO audit with the previous one. List new findings by severity with their suggested fixes, and separate fixed findings whose pages were not rechecked.Full access

Agency / consultant

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

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.Free preview
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.Full access
For [your site], combine the last 28 days of Search Console movement with linked GA4 landing-page sessions and key events for the same complete-day period. Keep query evidence separate from page-level Analytics outcomes, include both comparisons, and report truncation.Full + View analytics

Content lead / editor

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

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.Preview + full
For my pinned site, find target keywords whose intended page is not the page leading in Search Console clicks. For each, name both pages and say whether the evidence is capped or incomplete.Preview + full
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.Full access
For [your site], use CrawlRaven to list every available query attributed to exactly [page URL] from [start date] through [end date], following next_cursor until empty. Then inspect the current public page and propose page-specific refresh ideas. Separate Search Console evidence from content observations, state the exact period and rows inspected, report truncation, and do not call the bounded query set exhaustive.Full access
Plan a manual timeline note for [your site] on [date] titled [title]. Show me the exact proposal and approval link; do not say it changed until I approve it in CrawlRaven and status confirms completion.Full + Propose annotation changes

Developer / analyst

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

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.Preview + full
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.Full access

Just exploring

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

Show which CrawlRaven websites I can use, explain which one is available to this connection, and suggest three useful questions I can ask next without exceeding my access mode or changing any data.Preview + full

Scopes

A grant is bound to one user and the one account picked during consent. A paid connection can approve up to 11 scopes. Free preview is restricted to websites, Search Console performance, opportunities, and target keywords; it grants no Analytics, Technical SEO, annotation, or write scopes. Existing grants are never widened silently, so reconnect to review and approve a new permission.

Scope	Grants access to
`websites:read`	List websites available to the connection.
`search_performance:read`	Read Search Console overview, series, Query, and Page reports, plus paid imported Generative AI snapshots.
`opportunities:read`	Read active CrawlRaven opportunity records and the prioritized SEO plan.
`targets:read`	Read the durable Target Keywords plan and target-to-page alignment.
`annotations:read`	Read active website timeline annotations.
`analytics:read`	Read bounded reports from an already linked GA4 property.
`technical_seo:read`	Read stored Technical SEO audits, findings, and comparisons. Cannot start audits.
`opportunities:write`	Directly resolve, ignore, snooze, or reopen individual opportunities without further approval.
`targets:write`	Directly add target keywords, assign intended pages, and change priority without further approval.
`notes:write`	Directly create, edit, archive, and restore manual notes without further approval. Cannot change automatic events or permanently delete notes.
`annotations:write`	Propose manual annotation changes that require same-user approval in CrawlRaven before execution.

What a connection cannot do

Change Google Search Console, GA4 properties, websites, billing, administration, exports, or arbitrary API resources.
Change opportunity status, target keywords, or manual notes unless the matching write permission was approved. Write tools change one record at a time.
Start or refresh Technical SEO audits, refresh opportunities, or import Generative AI exports.
Change derived Google updates, opportunity events, or imports. Only manual notes can be written or proposed for change.
Permanently delete an annotation. MCP can archive and restore; permanent deletion is a separately confirmed, archived-note-only action in the first-party app.
Apply a proposed annotation plan without same-user review and approval in CrawlRaven, or overwrite a newer note version.
See any account other than the one selected during consent.
Fetch a URL, call a webhook, send email or touch files. Those tools do not exist here.
Follow a URL that appears inside a tool result, or let a value from one tool become the destination of another.

Search queries, page URLs and annotation text are customer data, so they come back as typed fields rather than as instructions a model should obey. Client-side controls such as Allow, Ask and Block are hints from tool annotations: convenience, not security. The server enforces its own policy even when a client is set to allow everything.

Data handling

The connector reads approved website metadata, Search Console reports, SEO opportunities, target keywords, linked GA4 aggregate reports, stored Technical SEO audits, imported Generative AI snapshots, and annotations from the CrawlRaven account selected during consent, each only when the grant includes its scope.

Search Console reports may be temporarily cached to improve reliability and avoid repeated requests to Google; MCP Analytics reporting does not persist GA4 report rows. CrawlRaven does not sell this data, use it for advertising, or use it to train AI models.

Tool results are sent to the connected client and processed under that client's and model provider's policies. Proposed annotation content is held only for the short-lived approval workflow; immutable content-free audit metadata records the client, action, resource versions, and outcome. Full details about storage, retention, deletion and subprocessors are in the CrawlRaven Privacy Policy.

How much data comes back

With paid access, a cursor-paginated list answers with one page at a time, sized to fit a model's context rather than a spreadsheet. The agent asks, the defaults below apply, and it fetches more pages if needed.

Tool	Full-access default	Full-access maximum	Time window
`list_queries`, `list_pages`	25	100	Rolling 1–365 days or exact inclusive dates spanning at most 365 days
`list_opportunities`, `list_target_keywords`	25	100	Not time-bound
`list_annotations`	100	200	1 to 400 days
`list_archived_annotations`	25	100	Not time-bound; cursor-paginated archive
`list_site_audits`, `get_site_audit`, `list_site_audit_findings`, `compare_site_audits`	25	100	Stored audits; not time-bound
`get_prioritized_seo_plan`	25	100	One bounded ranked result with no cursor; not time-bound
`get_target_page_alignment`, `get_page_query_mapping`	25	100	Cursor-paginated over a reporting window. A filtered page can be empty while next_cursor continues
`list_generative_ai_imports`, `get_generative_ai_pages`	10 imports; 50 pages	10 imports; 100 pages	The imported snapshot's own period, in Pacific Time
`get_analytics_breakdown`	25	100	Complete UTC days; bounded top rows with truncation, no cursor
`get_analytics_summary`	One result, not a list	Up to 365 daily rows	Complete UTC days ending no later than yesterday
`plan/status tools`	One plan or status	One plan or status	Plans must be approved within 15 minutes
`list_websites`	All, up to 100	100	Not time-bound
`get_website_overview`, `get_search_performance`	One result, not a list	Up to 365 daily rows	Rolling 1–365 days or exact inclusive dates spanning at most 365 days

Free preview has no pagination

Free preview returns its one pinned website, fixes Search Console tools to 28 days, and returns at most 50 Query, Page, Opportunity, or Target Keyword rows. Its next_cursor is always empty, and it cannot call Analytics, Technical SEO, Generative AI, annotation, or write tools. All users and clients on the account share 20 tool calls per UTC day.

With paid access, the agent goes past the first page of a cursor-paginated list by passing the next_cursor it just received back as cursor. Analytics breakdowns are bounded top-row reports instead: read their truncated flag rather than looking for a cursor. Two things are worth knowing about list cursors:

A cursor belongs to the exact request scope it came from. Change a filter, window, or exact page URL and the old cursor safely restarts at the first page, which prevents paging through a result set that no longer matches the question.
Every result says whether it was cut short, so an agent can tell "that is all of them" from "that is the first hundred" instead of guessing.

In practice this only surfaces when you ask something broad. Ask for the top queries and you get 25 useful rows straight away. Ask an agent to audit the bounded query corpus and it will page through the available rows, which takes longer and uses more of its context.

Errors

Code	Meaning	What to do
`401`	Token missing, invalid, expired, revoked, or issued for a different audience.	Let the client refresh, or reconnect if the grant is gone.
`403`	Valid token without the scope the tool needs, or a host or browser origin the server rejects.	Reconnect and approve the missing scope.
`forbidden`	The grant is no longer eligible, the required scope was not approved, or the free-preview website does not match.	Check the account’s access, reconnect for the intended account, and call list_websites for a current website_id.
`400`	Malformed authorization request.	Start the connection again from the client.
`conflict`	An annotation changed after the expected version was read, an idempotency key was reused for different content, a target keyword already exists, or an opportunity transition was repeated or invalid.	Re-read the current record, review the latest values, and retry only if the change is still wanted. For a note plan, use a new idempotency key.
`not_configured`	A required server-side capability is unavailable; this is not a prompt or credential problem.	Do not retry in a loop. Contact support with the request ID and no credentials.
`rate_limited`	A tool error carrying a retry hint rather than an HTTP status.	Wait for the hinted interval instead of retrying in a loop.

Annotation outcomes are statuses, not tool errors

A change plan reports pending_approval, applied, denied, conflict, expired, or cancelled. Pending plans also report whether they are awaiting_handoff or reviewing. Use get_annotation_change_status instead of repeating the mutation.

A tool call that cannot be fulfilled comes back as a tool error with a stable code, message, and request_id. Quote the request_id when you contact support. It is safe to share; never share the surrounding access token or client credentials.

Managing connections

Every client that has ever connected is listed on the MCP connections page in the app.

State	What it means
Active	Shows when the grant was last used and when it expires. Ninety days is the ceiling.
Plan required / access unavailable	The grant is still active and revocable, but its access mode is no longer eligible. Paid grants resume when paid access is restored.
Expired	Past its 90 days. Reconnect from the client for a fresh grant.
Revoked	Switched off by you. It cannot be reactivated.

Select Revoke beside an active client to invalidate its grant. Revocation is idempotent and takes effect on the client's next request, so a machine you no longer control loses access as soon as it tries to use it.

Before you connect

Anything a tool returns is processed by the client and its model provider under their policies. Connect only clients you are willing to share Search Console, linked GA4, opportunity, target, and annotation data with, and revoke the ones you were only trying out.

Troubleshooting

What you see	Why	What to do
MCP unavailable	You are not an owner/member of an eligible paid account, or the limited free preview is not enabled for an account with an activated website.	Use an eligible account, ask an owner/member to connect, or choose a plan from Billing.
Free preview limit reached	The account has used its shared allowance of 20 tool calls for the UTC day.	Wait until 00:00 UTC for the allowance to reset, or upgrade for full access.
Wrong free-preview website	Free access is pinned to the website chosen for the account’s first free grant.	Call list_websites to use the pinned website. Reconnecting does not switch it.
Connection shows Plan required	The access mode behind an active grant is no longer eligible.	Restore paid access for a paid grant, or upgrade if a free preview is no longer available. The grant remains revocable.
Authorization request expired	Authorization transactions are deliberately short-lived.	Start the connection again from the client.
No tools after approval	The client did not finish its redirect and token exchange.	Reconnect and let the browser tab return to the client before closing it.
Client registration failed	The client is outside what CrawlRaven accepts: CIMD or DCR, authorization code flow, S256 PKCE, HTTPS callbacks, HTTP loopback callbacks, or Cursor's exact application-owned callback.	Update the client, then retry.
Client is expired or revoked	Expired and revoked grants cannot be reactivated.	Start a new connection from the client.
Analytics, audit, or write tools are missing	The connection predates the new optional permission, the permission was not approved, or the account is using the free preview.	Reconnect the client and explicitly approve the permission you need on an eligible paid account.
Approval opens as the wrong user	The browser session does not belong to the user who authorized the MCP connection.	Sign in as the same authorizing user, then resume the approval. Another account member cannot approve it for you.
Annotation plan expired or conflicted	Approval did not happen within 15 minutes, or the annotation version changed before execution.	Read the latest annotation state and create a fresh plan. Never retry a stale plan blindly.
Wrong account	A different CrawlRaven account was selected during consent.	Revoke the grant, reconnect, and pick the intended account.

Support

Send connection questions to hello@crawlraven.com. Include the request ID shown by a failed tool call. Never send access tokens, refresh tokens, authorization codes, passwords or browser cookies.

Common questions

Do I need an API key or token to connect?

No. The client discovers CrawlRaven's authorization metadata and opens a browser sign-in. Never paste a personal access token, a Google token or a browser cookie into a client configuration.

Can a connected agent change anything in my account?

Only with a write permission you approve. Paid connections can request Manage opportunity status, Manage target keywords, or Manage manual notes directly, which change one record at a time without further approval. Propose annotation changes only plans note changes; the same authorizing user must approve each one in CrawlRaven. No tool changes Google services, websites, billing, or administration, derived events are immutable, and MCP cannot permanently delete a note.

Is MCP included in my plan?

Yes. Full MCP access is included with paid CrawlRaven access, whether it comes from an active subscription or a lifetime plan. Some free accounts can use the limited preview while that experiment is enabled.

What happens to my connections if my plan lapses?

They pause rather than disappear. The client stays listed and you can still revoke it, but tools stop returning data until the account has a paid entitlement again. Restoring the plan resumes the grant without reconnecting.

How is this different from the REST API?

CrawlRaven v2 does not currently offer a supported public REST API. MCP is the shipped integration for compatible AI clients: it describes each scoped tool so a model can choose one and returns typed data rather than a rendered page.

Does my data leave CrawlRaven when I connect an agent?

Yes, that is what the connection is for. Anything a tool returns is processed by the client and its model provider under their policies, so connect only clients you are willing to share Search Console, linked GA4, and CrawlRaven planning data with. Approval credentials are kept in the browser and are not returned to the client after exchange.