@htmldesk/mcp

MCP server and CLI for HtmlDesk — AI-native HTML document sharing.

Lets Claude Code / Claude Desktop / Codex (and your terminal) upload, share, and track HTML documents in your HtmlDesk workspace.

1. Get an API key

Sign in at https://htmldesk.com, then open API Keys (/private/__keys) and create a key. It looks like hd_live_… and is shown once — copy it.

2. Use it as an MCP server

Add to your MCP config (Claude Code ~/.claude.json / Claude Desktop claude_desktop_config.json / Codex):

{
  "mcpServers": {
    "htmldesk": {
      "command": "npx",
      "args": ["-y", "-p", "@htmldesk/mcp", "htmldesk-mcp"],
      "env": {
        "HTMLDESK_URL": "https://htmldesk.com",
        "HTMLDESK_API_KEY": "hd_live_xxxxxxxx"
      }
    }
  }
}

Then ask your AI to "upload this HTML to HtmlDesk and give me a share link."

3. Or use it as a CLI

export HTMLDESK_API_KEY=hd_live_xxxxxxxx      # from step 1
export HTMLDESK_URL=https://htmldesk.com      # optional (this is the default)

npx -p @htmldesk/mcp htmldesk upload report.html --folder reports/2026
npx -p @htmldesk/mcp htmldesk list --folder reports/2026
npx -p @htmldesk/mcp htmldesk share <doc_id> --expiry 7 --pin 1234
npx -p @htmldesk/mcp htmldesk url <doc_id>
npx -p @htmldesk/mcp htmldesk delete <doc_id>

(Install globally with npm i -g @htmldesk/mcp to drop the npx -p … prefix and just run htmldesk ….)

Environment variables

| Variable | Description | |----------|-------------| | HTMLDESK_API_KEY | Your per-workspace key (hd_live_…) → sent as X-Api-Key. Required. | | HTMLDESK_URL | Base URL. Defaults to https://htmldesk.com. |

MCP tools (14)

| Tool | Description | |------|-------------| | get_context | Workspace stats: folder tree, doc count, recent shares. Call first. | | get_catalog | Token-efficient index of all docs (~40 tokens/doc). | | upload_document | Upload HTML (inline or local file path). Returns doc_id. | | list_documents | List docs with optional folder/visibility filter. | | search_documents | Full-text search across your docs. | | get_document_markdown | Read a doc as Markdown (outline → full) without raw HTML. | | update_document | Update title or folder of an existing document. | | delete_document | Permanently delete a document and all its content. | | promote_document | Set visibility: private ↔ public. | | create_share | Create a Magic Link share (+ optional email). Returns share_id. | | get_view_logs | Check whether/when a recipient opened a share. | | revoke_share | Revoke a share immediately. | | get_comments | Read reviewer comments on a doc. | | resolve_comment | Mark a comment resolved. |

Typical workflow

1. get_context()                            → understand what already exists
2. upload_document(title, html|file_path)   → { doc_id }
3. promote_document(doc_id, "public")       → mark ready
4. create_share(doc_id, ["[email protected]"])   → magic link emailed
5. get_view_logs(share_id)                  → opened 2×, avg 4m30s
6. revoke_share(share_id)                   → lock when done

Requirements

Node.js ≥ 18 (uses the built-in fetch).