About spa-reader-mcp
spa-reader-mcp renders JavaScript-driven single-page applications and extracts their content as Markdown. It is for MCP clients that need readable page content or screenshots from sites that conventional scraping may miss.
Key features
- 01Render JavaScript-driven pages
- 02Extract content as Markdown
- 03Capture PNG screenshots
- 04Wait for a CSS selector
- 05Supply cookies and HTTP headers
- 06Block private and loopback IPs
Use cases
- 01Read content from a JavaScript-rendered page
- 02Capture a page after it loads
- 03Access pages using supplied cookies or headers
MCP support
The MCP server exposes page-reading and screenshot tools to MCP clients, using headless Chromium through Playwright.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
2Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | The URL of the SPA page to read |
| cookies | array | No | Cookies to inject before page load (e.g., session tokens) |
| headers | object | No | Custom HTTP headers (e.g., Authorization) |
| waitTimeout | number | No | Navigation timeout in ms (default: 30000) |
| includeMetadata | boolean | No | Include title/author/excerpt as YAML frontmatter (default: true) |
| waitForSelector | string | No | CSS selector to wait for before extraction |
Details
From the project READMEspa-reader-mcp
MCP server that renders JavaScript SPA pages and extracts Markdown via headless Chromium.
Traditional scrapers fail on SPAs because content is rendered client-side. This tool launches Playwright, waits for JS to finish, then extracts clean Markdown using Readability + Turndown.
Install
npx playwright install chromium
Claude Desktop
{
"mcpServers": {
"spa-reader": {
"command": "npx",
"args": ["-y", "spa-reader-mcp"]
}
}
}
Claude Code
claude mcp add spa-reader -- npx -y spa-reader-mcp
Tools
spa_read
Render a page and extract content as Markdown.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | URL to read (required) |
waitForSelector | string | — | CSS selector to wait for |
waitTimeout | number | 30000 | Timeout in ms |
includeMetadata | boolean | true | Add YAML frontmatter |
cookies | array | — | Cookies for auth |
headers | object | — | Custom HTTP headers |
spa_screenshot
Capture a PNG screenshot after JS rendering.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | URL to capture (required) |
waitForSelector | string | — | CSS selector to wait for |
waitTimeout | number | 30000 | Timeout in ms |
width | number | 1280 | Viewport width |
height | number | 720 | Viewport height |
fullPage | boolean | false | Full page capture |
cookies | array | — | Cookies for auth |
headers | object | — | Custom HTTP headers |
Security
- SSRF protection: blocks private/loopback IPs
- Only
http:andhttps:schemes allowed - Selector injection prevention
- Content capped at 100KB
Dev
pnpm install && pnpm build
pnpm test
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.