Reader MCP Server

MCP server for Reader - give AI agents the ability to read the web. Scrape pages, crawl sites, discover URLs, and create browser sessions through the Model Context Protocol.

Quick Start

Claude Code

claude mcp add reader -- npx -y @vakra-dev/reader-mcp

Then set your API key in the environment:

export READER_API_KEY=rdr_your_key_here

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "reader": {
      "command": "npx",
      "args": ["-y", "@vakra-dev/reader-mcp"],
      "env": {
        "READER_API_KEY": "rdr_your_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (Settings > Features > MCP Servers):

{
  "mcpServers": {
    "reader": {
      "command": "npx",
      "args": ["-y", "@vakra-dev/reader-mcp"],
      "env": {
        "READER_API_KEY": "rdr_your_key_here"
      }
    }
  }
}

VS Code

Add to your .vscode/mcp.json or user settings:

{
  "mcpServers": {
    "reader": {
      "command": "npx",
      "args": ["-y", "@vakra-dev/reader-mcp"],
      "env": {
        "READER_API_KEY": "rdr_your_key_here"
      }
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "reader": {
      "command": "npx",
      "args": ["-y", "@vakra-dev/reader-mcp"],
      "env": {
        "READER_API_KEY": "rdr_your_key_here"
      }
    }
  }
}

Codex

Add to your ~/.codex/config.toml:

[mcp_servers.reader]
command = "npx"
args = ["-y", "@vakra-dev/reader-mcp"]

[mcp_servers.reader.env]
READER_API_KEY = "rdr_your_key_here"

OpenCode

Add to your opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "reader": {
      "type": "local",
      "command": ["npx", "-y", "@vakra-dev/reader-mcp"],
      "enabled": true,
      "environment": {
        "READER_API_KEY": "rdr_your_key_here"
      }
    }
  }
}

Tools

reader_scrape

Scrape a single URL and return its content as clean markdown.

Parameters:

Name	Type	Required	Description
url	string	Yes	The URL to scrape
formats	string[]	No	Output formats: "markdown", "html", "screenshot". Default: ["markdown"]
proxyMode	string	No	"standard" (default) or "premium" for sites with bot detection
onlyMainContent	boolean	No	Extract main content only. Default: true
waitForSelector	string	No	CSS selector to wait for before scraping
includeTags	string[]	No	CSS selectors to include
excludeTags	string[]	No	CSS selectors to exclude
timeoutMs	number	No	Timeout in ms. Default: 30000

Example prompt: "Scrape https://example.com/blog/post-1 and summarize it"

reader_batch_scrape

Scrape multiple URLs in parallel. Creates an async job that processes all URLs and returns their content.

Parameters:

Name	Type	Required	Description
urls	string[]	Yes	List of URLs to scrape (1 to 1000)
formats	string[]	No	Output formats. Default: ["markdown"]
proxyMode	string	No	"standard" or "premium"
onlyMainContent	boolean	No	Extract main content only. Default: true

Example prompt: "Scrape these three blog posts and compare their main arguments: [url1, url2, url3]"

reader_crawl

Crawl a website starting from a URL, discovering and scraping all linked pages.

Parameters:

Name	Type	Required	Description
url	string	Yes	The starting URL to crawl from
maxDepth	number	No	Maximum link depth (1-10). Default: 2
maxPages	number	No	Maximum pages to crawl (1-10000). Default: 20
formats	string[]	No	Output formats. Default: ["markdown"]
proxyMode	string	No	"standard" or "premium"

Example prompt: "Crawl the docs at https://docs.example.com up to depth 3 and find all pages about authentication"

reader_discover

Discover all URLs on a website without scraping their content. Fast and cheap - 1 credit per job regardless of how many URLs are found.

Parameters:

Name	Type	Required	Description
url	string	Yes	The starting URL to discover from
maxDepth	number	No	Maximum link depth (1-10). Default: 2
maxPages	number	No	Maximum URLs to discover (1-10000). Default: 20

Example prompt: "Discover all URLs on https://example.com up to depth 2 and list the ones about pricing"

reader_extract

Scrape a URL and extract structured data using AI. Provide a JSON schema defining the data shape you want, or a natural language prompt, or both.

Parameters:

Name	Type	Required	Description
url	string	Yes	The URL to scrape and extract from
schema	object	No	JSON schema or shorthand (e.g. {"title": "string", "price": "number"})
prompt	string	No	Natural language instruction for what to extract
proxyMode	string	No	"standard" or "premium"

At least one of schema or prompt is required.

Example prompt: "Extract the product name, price, and features from https://example.com/product"

reader_job_status

Get the status and results of an async job (batch scrape, crawl, or discover).

Parameters:

Name	Type	Required	Description
jobId	string	Yes	The job ID

Example prompt: "Check the status of job abc123"

reader_cancel_job

Cancel a running async job.

Parameters:

Name	Type	Required	Description
jobId	string	Yes	The job ID to cancel

reader_session_create

Create a browser session with a CDP WebSocket endpoint for full browser automation with Playwright or Puppeteer.

Parameters:

Name	Type	Required	Description
maxDurationMs	number	No	Maximum session lifetime in ms. Default: 3600000 (60 min)

reader_credits

Check your credit balance and usage for the current billing period. Takes no parameters.

Environment Variables

Variable	Required	Description
READER_API_KEY	Yes	Your Reader API key. Get one at console.reader.dev
READER_API_URL	No	Custom API base URL for self-hosted Reader instances. Default: https://api.reader.dev

Pricing

Operation	Credits
Scrape (standard proxy)	1 per page
Scrape (premium proxy)	3 per page
Extract (adds to scrape cost)	+2 per page
Crawl	1 per page
Discover	1 per job (flat)
Browser session	1 per minute
Cache hit	0

License

MIT - see LICENSE for details.