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

An account is eligible when it holds a positive paid-feature allowance, which comes from a lifetime deal, an active subscription, or a support override. Both ends of the consent flow check it: you need at least one paid account to reach the consent screen, and the account you pick there must be a paid one.

The check runs again on every tool call, so entitlement is current rather than frozen at the moment you connected. If a plan lapses, existing grants stay visible and revocable but stop returning data until the account is paid again.

See pricing for the plans, 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 which paid CrawlRaven account to expose, and read the scopes requested. One grant covers 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 current catalog. A client only sees the tools covered by the scopes it was granted, so a narrower grant produces a shorter list.

Parameters

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.

Swap example.com for your own domain before pasting. An agent that cannot match the site will call list_websites and ask you which one you meant.

Scopes

A grant is bound to one user and the one account picked during consent. Inside that account, five scopes control what the client sees.

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.

How much data comes back

A list tool answers with one page at a time, sized to fit a model's context rather than a spreadsheet. You do not set any of this yourself. The agent asks, the defaults below apply, and it fetches more pages if it needs them.

To go past the first page, the agent passes 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 every query on the site and it will page through them, which takes longer and uses more of its context.

Errors

A tool call the API cannot fulfil comes back as a tool error carrying a stable code, a message, a request_id and whether it is worth retrying. Quote the request_id when you contact support. It is safe to share, because errors never carry tokens, Google responses or database identifiers.

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

Common questions