render-mcp

A Model Context Protocol server that renders PDFs, HTML, URLs, and images as screenshots. Purpose-built for giving AI coding assistants visual feedback on rendered artifacts.

Features

• Warm browser singleton -- Playwright Chromium stays running between requests, eliminating cold-start latency
• Native PDF rendering -- Uses pdftoppm (poppler) for fast, accurate PDF rasterization (~100ms per page, no browser)
• Image passthrough -- Direct file read for PNG, JPEG, GIF, WebP
• JPEG screenshots -- Browser screenshots use JPEG quality 80 for 5-10x smaller output vs PNG (same token cost)
• API-safe output -- 3.5 MB output guard ensures base64 stays under the Anthropic API's 5 MB image limit
• Per-request isolation -- Each browser render gets a fresh BrowserContext, closed in finally
• Single round-trip -- One tool call returns the image directly in context

Tools

Tool	Description	Browser?	Format
render_pdf	Render a PDF page as PNG	No	PNG
render_html	Render HTML string or file as JPEG	Yes	JPEG
render_url	Navigate to URL and screenshot	Yes	JPEG
render_image	Read image file as base64	No	Native

Installation

Prerequisites

• Node.js >= 20
• pdftoppm (poppler-utils) for PDF rendering

# macOS
brew install poppler

# Ubuntu/Debian
sudo apt-get install poppler-utils

From source

git clone https://github.com/LarsenClose/render-mcp.git
cd render-mcp
pnpm install
pnpm exec playwright install chromium
pnpm build

Claude Code

Add to your Claude Code MCP configuration:

claude mcp add --scope user --transport stdio render node /path/to/render-mcp/dist/index.js

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "render": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/render-mcp/dist/index.js"]
    }
  }
}

After restarting Claude Code, the tools are available as mcp__render__render_pdf, mcp__render__render_html, mcp__render__render_url, and mcp__render__render_image.

Tool Reference

render_pdf

Render a PDF page as a PNG image using pdftoppm.

Parameter	Type	Default	Description
path	string	required	Absolute path to the PDF file
page	number	1	Page number (1-indexed)
dpi	number	300	Resolution (72-600)

render_html

Render HTML content or an HTML file as a PNG screenshot.

Parameter	Type	Default	Description
html	string	--	HTML string to render
path	string	--	Absolute path to HTML file
width	number	1280	Viewport width in pixels
height	number	720	Viewport height in pixels
fullPage	boolean	false	Capture full scrollable page

Exactly one of html or path must be provided.

render_url

Navigate to a URL and return a PNG screenshot.

Parameter	Type	Default	Description
url	string	required	URL to navigate to
width	number	1280	Viewport width in pixels
height	number	720	Viewport height in pixels
fullPage	boolean	false	Capture full scrollable page
waitUntil	string	"load"	Navigation event: load, domcontentloaded, networkidle, commit

render_image

Read an image file and return it as base64.

Parameter	Type	Default	Description
path	string	required	Absolute path to image file

Supports: PNG, JPEG, GIF, WebP. SVG is not supported by the Anthropic API as an image block -- use render_html to rasterize SVGs.

Architecture

render-mcp (stdio transport)
|-- Warm Playwright Chromium (lazy singleton, auto-reconnect)
|-- PDF rendering via pdftoppm (no browser, ~100ms/page)
|-- Image passthrough (direct fs.readFile + base64)
'-- 3.5 MB output guard (keeps base64 under Anthropic's 5 MB API limit)

Key design decisions:

• chromium.launch() singleton (not launchPersistentContext) supports multiple isolated contexts
• New BrowserContext per request, closed in finally for full isolation
• Dependency injection for handlers enables unit testing with mocks
• pdftoppm for PDF over browser-based rendering for speed and accuracy

Development

pnpm install
pnpm exec playwright install chromium

pnpm test              # Run all tests
pnpm test:unit         # Unit tests only
pnpm test:integration  # Integration tests (InMemoryTransport)
pnpm test:e2e          # E2E tests (stdio subprocess)
pnpm test:coverage     # Tests with coverage report

pnpm typecheck         # TypeScript type checking
pnpm lint              # ESLint
pnpm format:check      # Prettier
pnpm build             # Compile to dist/

License

MIT