@ojodotso/mcp-server

oJo turns an HTML template and your JSON data into a PDF or PNG at a hosted link, from the REST API, any MCP client or the editor. This package is oJo's Model Context Protocol server. Live previews are free and need no account; an oJo API key adds hosted PNG and PDF links and reusable templates through the user's own account. Transport is local stdio; the API boundary is HTTP to https://api.ojo.so/v1 only.

Most clients can connect to https://mcp.ojo.so/mcp directly and sign in, without installing anything: see https://ojo.so/docs/mcp-server. This package is the local alternative.

Quick start — no account needed

Point your MCP client at the package. With no API key the server starts in preview-only mode: create_preview_link renders HTML into a live, full-resolution image preview, free and unlimited, with no oJo account.

{
  "mcpServers": {
    "ojo": {
      "command": "npx",
      "args": ["-y", "@ojodotso/mcp-server"]
    }
  }
}

claude mcp add ojo -- npx -y @ojodotso/mcp-server

Adding a key

A key unlocks the permanent PNG or PDF URL — the thing you can put in an email, a social card or an API response — plus reusable templates. Create one at https://ojo.so/dashboard/api and pass it as OJO_API_KEY:

{
  "mcpServers": {
    "ojo": {
      "command": "npx",
      "args": ["-y", "@ojodotso/mcp-server"],
      "env": { "OJO_API_KEY": "sk_..." }
    }
  }
}

claude mcp add ojo -e OJO_API_KEY=sk_... -- npx -y @ojodotso/mcp-server

Works the same for Claude Desktop, Cursor, and Claude Code.

Tools

Only create_preview_link is registered without an API key; the rest talk to the oJo API, so advertising them keyless would offer tools that can only fail.

Tool	Purpose	Credit	Needs a key
create_preview_link	Build a free, full-resolution /preview link for an HTML/Handlebars draft.	—	no
generate_image_from_html	Render plain HTML (with inline CSS) to a PNG; returns its public URL.	1	yes
generate_image_from_template	Render an existing template, optionally overriding variables via modify.	1	yes
generate_pdf_from_html	Render plain HTML (with inline CSS) to a PDF of up to 100 pages, A4 unless a CSS @page rule sets the size; returns its public URL, page count and credits spent. A longer document is refused and costs nothing.	1 per 20 pages	yes
generate_pdf_from_template	Render an existing template to a PDF, optionally overriding variables via modify, or build one PDF of up to 100 pages from many templates and HTML with pages.	1 per 20 pages	yes
list_templates	List the templates available to the account.	—	yes
get_template	Fetch one template's HTML and variable defaults.	—	yes
create_template	Create a reusable template from plain HTML/Handlebars.	—	yes
update_template	Replace a template's HTML, and its variable defaults when given, under the same ID. Overwrites: API renders use the new version at once.	—	yes

The design loop

Iterate with create_preview_link, then render. It returns an https://ojo.so/preview#draft=… URL that renders the draft live in the browser through the same engine as the final PNG, at full resolution. The draft is gzipped into the URL hash, so it never reaches a server and nothing is stored — the link is self-contained and shareable with a human reviewer. For a PDF the preview shows the screen rendering, not the page breaks.

Both image tools also accept inspect: true, which returns a 512px-wide downscaled thumbnail alongside the URL. That is a confirmation that the render succeeded, not a design surface — it is too small to judge layout or typography.

Guiding prompt

author_ojo_template — teaches the Handlebars helper catalog, the Template Variables (schema/defaults) vs Modify Payload (per-render data) model, viewport conventions, and the preview-first design loop.

Configuration

• OJO_API_KEY (optional) — your oJo API key. Without it the server runs in preview-only mode; with it the full tool surface is registered.
• OJO_API_BASE_URL (optional) — defaults to https://api.ojo.so/v1.
• OJO_WEB_BASE_URL (optional) — the web app that serves /preview for create_preview_link. Defaults to https://ojo.so; point it at a local http://localhost:3000 when developing against a self-hosted web app.

Develop

pnpm install
pnpm build
pnpm test
pnpm check