PaperSprocket

Name: PaperSprocket
Author: inde-x

@inde-xMCP server · External

EU-hosted HTML-to-PDF rendering for agents and MCP clients. Temporary document processing.

PDF toolsv1.0.0MITJavaScript

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

What it does

Reads
Writes
High impact

Not assessed yet.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

npmpapersprocket-mcpv1.0.0

Run

npx -y papersprocket-mcp

MCP client config

{
  "mcpServers": {
    "papersprocket": {
      "command": "npx",
      "args": [
        "-y",
        "papersprocket-mcp"
      ]
    }
  }
}

README4 min readView on GitHub

PaperSprocket MCP server

A Model Context Protocol (MCP) server that gives MCP clients direct access to the PaperSprocket API. It exposes exactly two tools:

Tool	Description
`render_html_to_pdf(html, page?)`	Render HTML to a PDF through the PaperSprocket API. Returns the PDF as an `application/pdf` MCP resource (base64 blob), a local file path when the server can write one, and render metadata (`render_id`, `page_count`, `charged_cents`, `balance_cents`). Billed to the configured account.
`check_balance(account_id)`	Read the prepaid balance of the configured PaperSprocket account. Returns `account_id`, `balance_cents`, `currency`, and `page_price_cents`.

This is a minimal native MCP server built directly on @modelcontextprotocol/sdk. No top-up tools, no API-key-management tools — just render and balance-check.

What is PaperSprocket?

PaperSprocket is a hosted API that turns HTML into PDFs. You send it HTML, it returns a well-formed PDF. There is no business-field schema to learn: you control the layout with your own HTML and CSS, PaperSprocket handles the PDF processing. See the official documentation.

Requirements

Node.js >= 20
A PaperSprocket API key. The server reads it from server-side config only (environment or .env) — it is never a caller-supplied tool argument, and is never embedded in source, examples, or this document.

Install

Run via npx (primary)

bash

npx -y papersprocket-mcp

The package papersprocket-mcp is published to npm and registered in the official MCP Registry under identity io.github.inde-x/papersprocket (active, version 1.0.0). Point your MCP client at npx -y papersprocket-mcp and provide PAPERSPROCKET_API_KEY in the client's environment (the server reads it server-side only).

From source (optional / development)

bash

git clone https://github.com/inde-x/papersprocket-mcp.git
cd papersprocket-mcp
npm ci
cp .env.example .env   # then set PAPERSPROCKET_API_KEY (see Configuration)

Configuration

The server loads <serverdir>/.env at startup (it does not override already-set environment variables). .env is gitignored.

Variable	Required	Default	Purpose
`PAPERSPROCKET_API_KEY`	yes	—	Your PaperSprocket API key. Secret/config state — never a tool argument.
`PAPERSPROCKET_BASE_URL`	no	`https://papersprocket.com/api`	API base URL. Fixed/config state.
`PAPERSPROCKET_MCP_OUTPUT_DIR`	no	`./output`	Directory where rendered PDFs are also written (best-effort) for filesystem-local clients.

Example .env (replace the placeholder — never commit a real key):

bash

PAPERSPROCKET_API_KEY=psk_your_api_key_here
# PAPERSPROCKET_BASE_URL=https://papersprocket.com/api
# PAPERSPROCKET_MCP_OUTPUT_DIR=./output

Run (stdio)

bash

node server.js                 # MCP over stdio
node server.js --list-tools    # print tool schemas, then exit

Connect an MCP client

Point your MCP client at a stdio server:

# primary — published npm distribution:
Command:   npx
Arguments: -y papersprocket-mcp

# or a local source checkout:
Command:   node
Arguments: /path/to/papersprocket-mcp/server.js

PAPERSPROCKET_API_KEY is provided via the server .env or environment — never in the client configuration.

MCP Inspector

bash

npx @modelcontextprotocol/inspector node /path/to/papersprocket-mcp/server.js

List tools → confirm exactly two: render_html_to_pdf and check_balance.

Tool schemas

`render_html_to_pdf`

json

{
  "html": { "type": "string", "description": "HTML to render (non-empty)." },
  "page": {
    "properties": {
      "size":            { "enum": ["A4", "Letter"] },
      "orientation":     { "enum": ["portrait", "landscape"] },
      "margin_mm":       { "top|right|bottom|left": { "type": "number", "minimum": 0, "maximum": 50 } },
      "print_background": { "type": "boolean" }
    }
  }
}

html — required, non-empty string.
page — optional. Defaults mirror the service's closed v1 schema: size A4, orientation portrait, margin_mm 10 on all sides, print_background true. Unknown fields are rejected.

Result (two MCP content blocks):

text — metadata JSON: tool, format, render_id, page_count, charged_cents, balance_cents, bytes, file_path, idempotency_key.
resource — application/pdf blob (base64) with a file:// (or urn:) URI.

`check_balance`

json

{ "account_id": { "type": "string" } }

account_id — required, non-empty string.

Result: { account_id, balance_cents, currency, page_price_cents } (text block).

Idempotency

A fresh random idempotency key is generated for each logical render.
On a transient network failure the server retries up to 2× reusing the same key, so a retry of one logical render cannot double-charge.
Server-side, PaperSprocket dedupes on (Idempotency-Key, request hash), so a true replay returns the original result without a second debit.

Security / secret boundary

PAPERSPROCKET_API_KEY is read from .env / environment — it is not a field in any tool input schema.
PAPERSPROCKET_BASE_URL is fixed/config state, not an agent-controlled argument.
The key is sent only as the Authorization HTTP header. No other credentials exist.
Rendered PDFs written to output/ are your own content; the directory is gitignored.