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.

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 full access.

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 the requested scopes. 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

Eight tools ship in the full catalog. A client only sees tools covered by its approved scopes. Free preview grants receive the first seven tools below; list_annotations is full-access only.

Parameters

Free preview fixes days at 28, caps list results at 50, and removes cursor. Full-access validation follows the parameter table above.

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, pagination, and the timeline.

Scopes

A grant is bound to one user and the one account picked during consent. Full access can approve five scopes. Free preview is restricted to websites, search performance, opportunities, and target keywords; it does not grant annotations:read.

What a connection cannot do

• Edit or delete anything. The catalog has no write tools.
• Reach billing, administration, exports or arbitrary API endpoints.
• 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, 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. 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. Full details about storage, retention, deletion and subprocessors are in the CrawlRaven Privacy Policy.

How much data comes back

With full access, a list tool 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 full access, the agent goes past the first page by passing the next_cursor it just received back as cursor. Two things are worth knowing about that:

• A cursor belongs to the exact search it came from. Change a filter or a window and the old cursor stops working, which is deliberate: it would otherwise page 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