oJo — HTML to image and PDF MCP server

@ojodotso/mcp-server

A Model Context Protocol server that lets an AI agent turn HTML into images. Live previews are free and need no account; an oJo API key adds hosted PNG URLs 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.

Quick start — no account needed

Point your MCP client at the package. With no API key the server starts in preview-only mode: createpreviewlink 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 URL — the thing you can put in an email, a social card or an API response — plus reusable templates. Create one at and pass it as OJOAPIKEY:

{
  "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 createpreviewlink is registered without an API key; the rest talk to the oJo API, so advertising them keyless would offer tools that can only fail.

The design loop

Iterate with createpreviewlink, 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.

Both generate 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

authorojotemplate — 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

preview-only mode; with it the full tool surface is registered.

• OJOAPIKEY (optional) — your oJo API key. Without it the server runs in

createpreviewlink. Defaults to https://ojo.so; point it at a local http://localhost:3000 when developing against a self-hosted web app.

• OJOAPIBASE_URL (optional) — defaults to https://api.ojo.so/v1.
• OJOWEBBASE_URL (optional) — the web app that serves /preview for

Develop

pnpm install
pnpm build
pnpm test
pnpm check