Converts HTML templates and JSON data into hosted PDF or PNG images via an API.
Also known as ojodotso/mcp-server, mcp-server, @ojodotso/mcp-server
- Stars
- 0
- Tools
- 1
- Downloads, 30 days
- —
- Latest version
- 0.9.0
- Last commit
- Oct 28, 2026
- License
- MIT
What is oJo MCP?
oJo converts HTML templates and JSON data into hosted PDF or PNG images via an API. It exposes 1 tool, such as create_preview_link.
Summary generated from the project's README
About oJo MCP server
Transforming HTML templates and JSON data into hosted PDF or PNG files is what oJo enables for developers using MCP clients like Claude Desktop, Cursor, or Claude Code. The server operates via local stdio and connects to a remote API to handle rendering tasks. Users can run the server in a preview-only mode without an account to generate full-resolution image previews using the create_preview_link tool.
To access permanent hosted links and reusable templates, you must provide an OJO_API_KEY. Once authenticated, you can use tools such as generate_image_from_html, generate_pdf_from_template, and list_templates. The server supports rendering plain HTML with inline CSS or using Handlebars templates with variable overrides. For PDF generation, the system handles documents up to 100 pages in A4 format unless specified otherwise via CSS. This setup allows for a rapid design loop where you can iterate on drafts before committing to a final render.
What you can do with it
- 1Generate free visual previewsCreate a shareable, full-resolution link to review an HTML draft without needing an account.
- 2Convert HTML to PNGRender plain HTML content with inline CSS into a public PNG image URL.
- 3Produce multi-page PDF documentsTransform HTML or existing templates into a PDF document of up to 100 pages.
- 4Manage reusable templatesCreate, update, and list HTML templates stored in your account for repeated use.
Written from the project's README. Every use case is checked against a quote from it.
How to install oJo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall oJo MCP in Claude Code
$ claude mcp add --env 'OJO_API_KEY=<YOUR_OJO_API_KEY>' mcp-server -- npx -y @ojodotso/mcp-serverInstall oJo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@ojodotso/mcp-server"
],
"env": {
"OJO_API_KEY": "<YOUR_OJO_API_KEY>"
}
}
}
}Install oJo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ojodotso/mcp-server"
],
"env": {
"OJO_API_KEY": "<YOUR_OJO_API_KEY>"
}
}
}
}Install oJo MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@ojodotso/mcp-server"],"env":{"OJO_API_KEY":"<YOUR_OJO_API_KEY>"}}'Install oJo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@ojodotso/mcp-server"
],
"env": {
"OJO_API_KEY": "<YOUR_OJO_API_KEY>"
}
}
}
}Install oJo MCP in Codex
$ codex mcp add mcp-server --env 'OJO_API_KEY=<YOUR_OJO_API_KEY>' -- npx -y @ojodotso/mcp-serverInstall oJo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@ojodotso/mcp-server"] [mcp_servers.mcp-server.env] OJO_API_KEY = "<YOUR_OJO_API_KEY>"
Install oJo MCP in Gemini CLI
$ gemini mcp add -s user -e 'OJO_API_KEY=<YOUR_OJO_API_KEY>' mcp-server npx -- -y @ojodotso/mcp-serverInstall oJo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@ojodotso/mcp-server"
],
"env": {
"OJO_API_KEY": "<YOUR_OJO_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @ojodotso/mcp-server 0.9.0 in an isolated container with no network and no keys. It answered and listed 1 tool.
oJo MCP tools 1
Read from the server with tools/listcreate_preview_linkRead-onlyRender HTML/Handlebars into a live, full-resolution image preview — free, unlimited, and with no oJo account. Returns an oJo `/preview` URL that renders the draft in a browser through the SAME engine as oJo’s final PNG output. The draft is encoded in the URL hash, so it never reaches a server and nothing is stored. Open it and screenshot it, or hand the link to a human for review. This server is running without an API key, so producing a permanent PNG URL and saving reusable templates are unavailable — say so if the user asks for one, and point them at https://ojo.so/dashboard/api.
Configuration
OJO_API_KEYSecretoJo API key — create one at https://ojo.so/dashboard/api. Optional: without it the server runs in preview-only mode, where create_preview_link renders free full-resolution previews with no account.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@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 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
oJo MCP questions
How do I add oJo MCP to Claude Code?
Run claude mcp add --env 'OJO_API_KEY=<YOUR_OJO_API_KEY>' mcp-server -- npx -y @ojodotso/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add oJo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does oJo MCP provide?
It exposes 1 tool, including create_preview_link.
Do I need an account to use oJo?
No, you can use the server in preview-only mode without an account to create free, unlimited live image previews.
How can I get permanent links for my images and PDFs?
You need to provide an oJo API key via the OJO_API_KEY environment variable to unlock permanent hosted URLs.
What is the maximum length for a PDF document?
The server can render PDFs of up to 100 pages; longer documents will be refused.