@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: 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 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 |
list_templates | List the templates available to the account. | — | yes |
get_template | Fetch one template's decoded HTML and variable defaults. | — | yes |
create_template | Create a reusable template from plain HTML/Handlebars. | — | 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.
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
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 tohttps://api.ojo.so/v1.OJO_WEB_BASE_URL(optional) — the web app that serves/previewforcreate_preview_link. Defaults tohttps://ojo.so; point it at a localhttp://localhost:3000when developing against a self-hosted web app.
Develop
pnpm install
pnpm build
pnpm test
pnpm check