Vercel AI SDK

Give AI SDK agents MrScraper tools: retrieve public pages as Markdown, HTML, or screenshots, search Google, and check account usage with @mrscraper/ai-sdk.

The @mrscraper/ai-sdk package provides MrScraper tools for the Vercel AI SDK. Pass them to generateText, streamText, or an agent, and the model can retrieve web pages, search Google, and check your MrScraper usage while it works.

Requirements

AI SDK 7 and Node.js 18 or later.
A MrScraper API key from app.mrscraper.com/api-tokens.

Install

npm install @mrscraper/ai-sdk ai zod

Set your key as an environment variable:

export MRSCRAPER_API_KEY="your_mrscraper_api_key"

The tools read MRSCRAPER_API_KEY, then MRSCRAPER_API_TOKEN. To pass the key in code instead, use mrscraperTools({ apiKey }).

Quick start

import { generateText, isStepCount } from "ai";
import { mrscraperTools } from "@mrscraper/ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5",
  prompt:
    "Read https://www.scrapethissite.com/pages/simple/ and list the five countries with the largest area.",
  tools: mrscraperTools(),
  stopWhen: isStepCount(5),
});

mrscraperTools() returns scraperAPI, webSearch, and status, the same names the MrScraper MCP server uses. To add only some of them, use the individual factories:

import { scraperApiTool, webSearchTool } from "@mrscraper/ai-sdk";

const tools = {
  scraperAPI: scraperApiTool(),
  webSearch: webSearchTool(),
};

Tools

Tool	Inputs	Returns
`scraperAPI`	`url`; `formats` (`markdown`, `html`, `screenshot`; default `markdown`); optional `browserRendering`, `waitForSelector`, `geoCode`, `timeout`	The requested formats, the API status code, and the tokens used
`webSearch`	`query` (search terms or a Google search URL); optional `region`, `language`, `page`	Organic results (`rank`, `title`, `link`, `description`, `source`), "People also ask" entries, and the next page number
`status`	None	Subscription status, token limit, tokens used, and tokens remaining

Screenshots are sent to the model as images rather than as base64 text. scraperAPI and webSearch use tokens from your plan; status uses none.

Errors

API errors, such as an invalid key or an exhausted plan, are thrown from the tool. The AI SDK reports them to the model as tool errors, so the model can explain the problem or try another approach. The API key is never included in an error message.

MCP server: connect MCP clients such as Claude, Cursor, or ChatGPT instead.
Node.js SDK: call the MrScraper API directly.
Source on GitHub