OJo — HTML to image README

@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.

config.json

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

Terminal

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:

config.json

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

Terminal

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

bash

pnpm install
pnpm build
pnpm test
pnpm check