CrawlRaven MCP server

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 data with a short text summary attached, so a model receives the rows themselves rather than a rendered dashboard. Typical calls: which queries lost clicks over 90 days, what to work on this week from the opportunity list, whether a Google update lines up with a drop in the daily rows, which GA4 landing pages produced outcomes, or whether to approve a proposed manual timeline note.

Availability

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 View analytics or Manage annotations 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

1. 01

   Add the server URL

   In the MCP or connector settings of an OAuth-capable client, add https://mcp.crawlraven.com/mcp as the server.

2. 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.

3. 03

   Review the consent screen

   Check the client name, choose an eligible CrawlRaven account, and read every requested permission. View analytics and Manage annotations are separate paid permissions. A free preview also asks for its pinned website. One grant covers one client, one user, and one account.

4. 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.

5. 05

   Call list_websites

   It returns the website_id every other tool needs.

Client setup

https://mcp.crawlraven.com/mcp

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

https://mcp.crawlraven.com/mcp

codex mcp login crawlraven

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

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.

Tools

Thirteen tools are available across all paid permissions. A client only sees tools covered by its approved scopes. Free preview grants receive the seven rows marked Paid + preview; Analytics and all annotation tools are unavailable in preview.

Parameters

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, active annotations, archived annotations, or annotation planning.

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.

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.

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.

Scopes

A grant is bound to one user and the one account picked during consent. A paid connection can approve up to seven scopes. Free preview is restricted to websites, Search Console performance, opportunities, and target keywords; it grants neither Analytics nor annotation read/write scopes. Existing grants are never widened silently—reconnect to review and approve a new permission.

What a connection cannot do

• Change Google Search Console, GA4 properties, websites, targets, opportunities, billing, administration, exports, or arbitrary API resources.
• Change derived Google updates, opportunity events, or imports. Only manual annotations can be proposed for mutation.
• 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 manual 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, and—when the grant includes the scope—annotations from the CrawlRaven account selected during consent. 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.

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

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.

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.

Troubleshooting

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