htmlbook

htmlbook

Publish AI-generated HTML and Markdown to a hosted, shareable URL. htmlbook is an MCP server and REST API that takes a document your coding agent just generated — an HTML report, a data dashboard, a spec, meeting notes, an interactive page — and turns it into a clean link you can open on your phone or send to someone, instead of leaving it as a local .html file buried in a project folder.

Push from Claude Code, Cursor, Codex, or claude.ai. htmlbook stores the document, re-themes it for comfortable reading on any device (paper / sepia / dark), keeps every edit as a version, and gives each document one share link with three modes — public (anyone, no login), password-protected (anyone with the password, no login), or a private secret link only you and your workspace can open.

Share the output as a link, not a file. When an agent makes HTML, the awkward part is everything after: getting it off your laptop, onto your phone, in front of someone else. htmlbook is the shelf that part lives on.

• 🌐 Website: <https://htmlbook.io>
• 🔌 MCP endpoint: https://htmlbook.io/api/mcp
• 📡 REST publish: POST https://htmlbook.io/api/docs
• 💬 Community: Discord

---

Quickstart

1. Connect your agent

Get an API key at <https://htmlbook.io> → Settings, then add the MCP server.

Claude Code (browser login, no key needed):

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp
# then run `claude` and approve the htmlbook login

Claude Code (with an API key):

claude mcp add --transport http htmlbook https://htmlbook.io/api/mcp \
  --header "Authorization: Bearer $HTMLBOOK_API_KEY"

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "htmlbook": {
      "url": "https://htmlbook.io/api/mcp",
      "headers": { "Authorization": "Bearer hb_live_REPLACE_WITH_YOUR_KEY" }
    }
  }
}

Codex CLI — ~/.codex/config.toml:

[mcp_servers.htmlbook]
url = "https://htmlbook.io/api/mcp"
bearer_token_env_var = "HTMLBOOK_API_KEY"

claude.ai / Claude Desktop — add a custom connector with URL https://htmlbook.io/api/mcp (OAuth — no key to paste).

See docs/getting-started.md for every client.

2. Publish a document

Just ask your agent. With the MCP server connected, it calls the publish tool:

You: Write up the Q3 numbers as a dashboard and put it on htmlbook.

Agent: htmlbook → publish
       ✓ shelved (hbdoc) · acme/q3-dashboard · v1 · read: https://htmlbook.io/app/p/acme/q3-dashboard

Prose (a report, a plan, notes) is easiest as Markdown — htmlbook keeps the .md as the source of truth and renders a themed reader view from it:

{
  "tool": "publish",
  "project": "acme",
  "markdown": "# Q3 Review\n\nRevenue is up 8% QoQ...\n\n## Highlights\n- ..."
}

3. Share it

Documents are private by default. Make one public to get a link anyone can open:

Agent: htmlbook → set_access  (visibility: public)
       ✓ acme/q3-dashboard is now public · https://htmlbook.io/d/a1b2c3

That's the whole loop: generate → publish → share.

---

What you can publish

| Format | When | What htmlbook does | |--------|------|--------------------| | Markdown | Prose: reports, plans, notes, specs | Keeps the .md as the source of truth, renders a themed reader view (TOC, tables, callouts, task lists), stays downloadable + editable as Markdown | | hb-doc HTML | Rich docs: dashboards, KPIs, inline SVG charts | A <article class="hb-doc"> fragment styled only with hb- classes + --hb- tokens — the reader supplies the stylesheet and re-themes it (paper / sepia / dark, width, font size) | | Bundle | A self-contained page with its own CSS/JS | Stored verbatim and rendered in a sandboxed iframe — your scripts run, your styling is preserved. Can be multi-file (index.html + sub-pages + assets, ≤10MB) for a small static site with working relative links |

The format is auto-detected at publish. You never have to declare it — push Markdown, push an hb-doc fragment, or push a full standalone HTML page and htmlbook routes it.

See docs/publishing.md and docs/hb-doc-contract.md.

---

Why htmlbook

• Off your laptop. An agent's HTML output is stuck on the machine that made it.

htmlbook gets it onto your phone and into a shareable link.

• Readable everywhere. Because an hb-doc carries no CSS of its own, the reader

themes it — the same document looks right on a phone in the dark and a desktop in daylight.

• Versioned. Every publish and every in-reader edit is a new immutable version.

The History panel shows who changed what; any version restores.

• Markdown stays Markdown. A Markdown push is not lossily converted to HTML — the

original .md is the source of truth and round-trips on download.

• Private by default. Nothing is public until you flip it. Three share modes:

public (anyone), password-protected (anyone with the password, no login — changing it revokes prior access), or a secret link session-gated to your workspace.

• Token-cheap. Push a large document as a file over the REST API so its bytes

never pass back through your agent's context. See docs/rest-api.md.

---

The MCP tools

The htmlbook MCP server exposes 10 tools. Full reference: docs/mcp-tools.md.

| Tool | Purpose | |------|---------| | publish | Shelve a document (HTML or Markdown) to a hosted URL; new version if it exists | | guide | Get the authoring contract (hb-doc classes, tokens, components) before composing HTML by hand | | list | Browse your library, optionally filtered by project | | get | Fetch a document's metadata + current body (for markdown, the .md source) | | search | Full-text search across everything you've shelved (recall before re-deriving) | | organize | Set title / tags / path, move between projects, rename | | set_access | Make a document public, password-protected, or private | | cite | Get a shareable deep-link to a specific section (heading) of a document | | restore | Roll a document back to an earlier version | | delete | Move a document to the trash |

---

Supported clients

| Client | Auth | |--------|------| | Claude Code | API key over MCP, or browser login; also REST | | Cursor | API key over MCP | | Codex CLI | API key over MCP; also REST | | claude.ai | OAuth (custom connector) | | Claude Desktop | OAuth (custom connector) | | Any MCP client | Streamable HTTP + Bearer key or OAuth 2.1 |

---

Documentation

• Getting started — connect every client, get a key
• Publishing — the three formats, the publish tool, examples
• Markdown — source of truth, frontmatter, folder sync
• The hb-doc contract — classes, tokens, components
• Sharing & access — public, password, secret links, workspaces
• MCP tools reference — all 10 tools with example calls
• REST API — POST /api/docs, token-cheap file pushes
• examples/ — a report, a dashboard, a folder-sync setup

---

Made by Streamize. Documentation is MIT-licensed; htmlbook itself is a hosted service at htmlbook.io.