oJo — HTML to image and PDF

@ojodotso/mcp-server

oJo 可将 HTML 模板和 JSON 数据转换为 PDF 或 PNG，并生成托管链接；你可以通过 REST API、任意 MCP 客户端或编辑器使用。本软件包是 oJo 的 Model Context Protocol 服务。实时预览免费且无需账户；oJo API 密钥可通过用户自己的账户生成托管 PNG 和 PDF 链接，并使用可重复利用的模板。传输方式为本地 stdio；API 边界仅通过 HTTP 连接到 https://api.ojo.so/v1。

大多数客户端都可以直接连接到 https://mcp.ojo.so/mcp 并登录，无需安装任何内容：参见 https://ojo.so/docs/mcp-server。本软件包是本地替代方案。

快速开始 — 无需账户

将 MCP 客户端指向本软件包。未提供 API 密钥时，服务会以 仅预览模式启动：create_preview_link 会将 HTML 渲染为实时、全分辨率的图像预览，免费且不限次数，无需 oJo 账户。

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

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

添加密钥

密钥可解锁永久 PNG 或 PDF URL——你可以将其放入电子邮件、社交卡片或 API 响应中——并使用可重复利用的模板。请在 https://ojo.so/dashboard/api 创建密钥，并将其作为 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

Claude Desktop、Cursor 和 Claude Code 的操作方式相同。

工具

未提供 API 密钥时，仅注册 create_preview_link；其余工具会调用 oJo API，因此在无密钥时展示它们并无意义，因为这些工具只会失败。

工具	用途	点数	需要密钥
create_preview_link	为 HTML/Handlebars 草稿生成免费的全分辨率 /preview 链接。	—	否
generate_image_from_html	将纯 HTML（含内联 CSS）渲染为 PNG；返回其公开 URL。	1	是
generate_image_from_template	渲染现有模板，可通过 modify 覆盖变量。	1	是
generate_pdf_from_html	将纯 HTML（含内联 CSS）渲染为最多 100 页的 PDF，除非 CSS @page 规则指定尺寸，否则使用 A4；返回其公开 URL、页数和消耗的点数。超过页数限制的文档将被拒绝，且不收费。	每 20 页 1 点	是
generate_pdf_from_template	将现有模板渲染为 PDF，可通过 modify 覆盖变量；也可使用 pages，通过多个模板和 HTML 生成一份最多 100 页的 PDF。	每 20 页 1 点	是
list_templates	列出账户可用的模板。	—	是
get_template	获取一个模板的 HTML 和变量默认值。	—	是
create_template	使用纯 HTML/Handlebars 创建可重复利用的模板。	—	是
update_template	在相同 ID 下替换模板的 HTML；若提供变量默认值，也一并替换。会覆盖原内容：API 渲染会立即使用新版本。	—	是

设计流程

使用 create_preview_link 反复迭代，然后再进行渲染。它会返回一个 https://ojo.so/preview#draft=… URL，通过与最终 PNG 相同的引擎在浏览器中实时渲染草稿，且为全分辨率。草稿会经过 gzip 压缩并放入 URL 哈希中，因此不会发送到服务器，也不会保存——该链接内容自包含，可与人工审核者分享。对于 PDF，预览显示的是屏幕渲染效果，不显示分页。

两个图像工具也接受 inspect: true，该选项会在 URL 旁返回一张宽度为 512px 的缩小缩略图。这只能确认渲染成功，并非设计画布——尺寸太小，无法判断布局或排版。

引导提示词

author_ojo_template — 介绍 Handlebars 助手目录、模板变量（架构/默认值）与修改载荷（每次渲染的数据）模型、视口规范，以及预览优先的设计流程。

配置

• OJO_API_KEY（可选）——你的 oJo API 密钥。未设置时，服务以仅预览模式运行；设置后则会注册完整的工具集。
• OJO_API_BASE_URL（可选）——默认为 https://api.ojo.so/v1。
• OJO_WEB_BASE_URL（可选）——为 create_preview_link 提供 /preview 的 Web 应用。默认为 https://ojo.so；使用自托管 Web 应用进行开发时，可将其指向本地地址 http://localhost:3000。

开发

pnpm install
pnpm build
pnpm test
pnpm check