# HTMLRadar MCP server

> Allows an AI agent to publish tracked web pages, control recipient access, monitor reading engagement, and update content via a single link.

- Repository: https://github.com/htmlradar/htmlradar-mcp
- Page: https://hostedmcp.org/servers/htmlradar/htmlradar-mcp
- Transport: stdio, remote
- Stars: 0
- Latest version: 0.9.0

## Install

### Claude Code

```sh
claude mcp add --env 'HTMLRADAR_API_KEY=<YOUR_HTMLRADAR_API_KEY>' htmlradar-mcp -- npx -y htmlradar-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "htmlradar-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "htmlradar-mcp"
      ],
      "env": {
        "HTMLRADAR_API_KEY": "<YOUR_HTMLRADAR_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "htmlradar-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "htmlradar-mcp"
      ],
      "env": {
        "HTMLRADAR_API_KEY": "<YOUR_HTMLRADAR_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"htmlradar-mcp","type":"stdio","command":"npx","args":["-y","htmlradar-mcp"],"env":{"HTMLRADAR_API_KEY":"<YOUR_HTMLRADAR_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "htmlradar-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "htmlradar-mcp"
      ],
      "env": {
        "HTMLRADAR_API_KEY": "<YOUR_HTMLRADAR_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add htmlradar-mcp --env 'HTMLRADAR_API_KEY=<YOUR_HTMLRADAR_API_KEY>' -- npx -y htmlradar-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.htmlradar-mcp]
command = "npx"
args = ["-y", "htmlradar-mcp"]

[mcp_servers.htmlradar-mcp.env]
HTMLRADAR_API_KEY = "<YOUR_HTMLRADAR_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'HTMLRADAR_API_KEY=<YOUR_HTMLRADAR_API_KEY>' htmlradar-mcp npx -- -y htmlradar-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "htmlradar-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "htmlradar-mcp"
      ],
      "env": {
        "HTMLRADAR_API_KEY": "<YOUR_HTMLRADAR_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `HTMLRADAR_API_KEY` | yes | yes | HTMLRadar API key, created at https://htmlradar.com/settings under "API keys". Starts with hr_live_. |

## Tools (16)

- `share_html`: Publishes an HTML document (a deck, report, dashboard, proposal or one-pager) as a tracked HTMLRadar link, and returns two addresses: the link for the recipient, and a dashboard address for the sender. The recipient sees the document as written and never the tracking. The markup goes in `html`; there is no file-path argument, so a file on disk is published by passing its markup. By default the recipient is asked for their email address before the document opens. The new HTML is screened for phishing signals as every upload is; the link is live the moment it is returned unless the screen holds the page, and readers of a held page see that it is not available yet. The answer includes the saved rules and whether comments are on. The document id that create_share and replace_document take comes from list_documents or list_shares. Markup is limited to 5 MB. Images that need a login, expiring image addresses and local file paths do not load for readers of the link; an image embedded in the HTML as a data URI travels inside the page. The tool does not check that images load.
- `create_share`: Creates an additional tracked link for a document already on HTMLRadar, with its own recipient label, gate, password, expiry and address. One link per recipient is what separates their reading reports. It uploads nothing and creates no second copy of the document, and it cannot publish new markup. The document id comes from list_documents or list_shares. The link is live the moment it is returned, but a held or blocked document does not open for readers through any link. The answer includes the saved rules and whether comments are on.
- `list_shares`: Lists the account's tracked links, newest first: the slug, the recipient label, the document title, whether it has been opened and when, and the share and document ids for each link. A link made in an earlier conversation is found here. The `opened` and `last_open` fields show which links nobody has opened. Returns at most 50 per call; the `before` cursor pages back through older links. (read-only)
- `list_documents`: Lists the account's documents, newest first: the title, when it was created, how many tracked links point at it, and its document id. A document with no links appears here and not in list_shares, which lists only documents that have been sent. It returns no document contents. Returns at most 50 per call; the `before` cursor pages back through older documents. (read-only)
- `get_share_activity`: Reports whether a tracked HTMLRadar link has been opened and how many read it. For each reader shown in full, it reports who they are, how long they read, how far they scrolled, and all recorded sections ordered by reading time. On Free, the first five readers of a link are shown in full; later readers appear as a "more read it" count. Reading times are rounded down; scroll percentages are rounded to the nearest whole percent. It accepts the link's share id, slug or full address. With `include_detail`, each reader shown in full has their country, city, device and referring page added. (read-only)
- `revoke_share`: Switches off a tracked link that has already been sent. Anyone who opens it afterwards sees that it is no longer available, and the sender is emailed that somebody tried, at most once every six hours for a link. This changes what a recipient can see. It is reversible: `revoked: false` switches a link back on, however long ago it was switched off, but a link past its end date stays closed until update_share sets a new end date or clears it. It deletes nothing: the link, its settings and its whole reading history survive. Deleting a link is possible only on the website, because it deletes its reading records for good. update_share changes a link's settings without changing its address; switching one off to make a replacement leaves the recipient holding a dead address.
- `get_share`: Returns a tracked link's current settings, in the form update_share changes them: who can open it (the full allowed-domain and allowed-address lists), the email gate and its one-time code, whether a password is set (never the password), the end date, the copy lock, comments, the label, who the gate names, whether the sender is emailed on the first open, and the settings version. It reads one of this account's links and changes nothing. The answer includes the saved rules and the settings version that update_share takes as expected_settings_version. (read-only)
- `update_share`: Changes the settings of a tracked link that has already been sent, on the same link: who can open it (allowed domains and addresses), the email gate and its one-time code, the password, the end date, the copy lock, the label, who the gate names and whether the sender is emailed on the first open. Comments can be on or off; enabling needs a code-confirmed email gate. The answer includes the saved rules. The link, its address and its whole reading history stay the same. Only the settings named in the call change; every other setting is left as it is, and a setting is removed when it is named in `clear` (a recipient_label of only spaces also removes the label). The list arguments add_allowed_emails, remove_allowed_emails, add_allowed_email_domains and remove_allowed_email_domains: the server merges them over the stored list and says what was added, removed and not found. Replacing or clearing a whole list (sending allowed_emails or allowed_email_domains, or naming one in `clear`) needs expected_settings_version, the settings version get_share returned, so a change made since is never overwritten. A stale version is refused without saving. A change applies from the next time the page is loaded: someone reading it right now keeps the page they have until they reload. If the sender is on a company team, the team's rules apply to this change exactly as on the website (for example a required one-time code or company domains), and a change that breaks one is refused with the rule named. Narrowing who can open a link, or removing a list, changes what recipients can see.
- `list_attachments`: Lists the files attached to a document on HTMLRadar (supporting materials a reader can download beside the page): the file name, its size and the attachment id. It returns no file contents and changes nothing. After an add_attachment call that gave no answer, this list shows whether the file was attached. (read-only)
- `add_attachment`: Attaches one file to a document already on HTMLRadar, for readers of its links to download. The file types are the website's (PDF, Office documents, images, CSV, text, Markdown, ZIP) and a document holds up to 20 files. The file travels as base64 in `content_base64`, because a tool argument is JSON, so it can be at most 5.0 MB, the same limit as publishing a page this way; a larger file (the website takes 25 MB) is added on the website. Readers see the file from the next time they load the page. There is no file-path argument.
- `remove_attachment`: Removes one attached file from a document. Downloads stop at once, even from a page a reader already has open; the file leaves the page's list the next time the page loads. Copies a reader already downloaded stay with them. It removes the file only: the page, its links and its reading history are untouched, and there is no tool that deletes a page or a link. The file cannot be recovered from HTMLRadar; attaching it again needs the original file. list_attachments returns the attachment id.
- `get_reading_records`: Returns the reading records the HTMLRadar website exports as a spreadsheet, as CSV text: for readers shown in full, one row per section per read (a read with no section recorded has one row with the section columns blank; section_status says "not measured" when the page changed while it was being read, so no section time was taken), with the link's label and slug, the reader, whether their address was verified, when they opened it, how long they read, how far they scrolled, and their country and device where recorded. On Free, the first five readers of a link are shown in full; later readers appear in a "more read it" count row without their individual details. The sender's own previews and internal viewers are left out, as on the website. With `share_id`, the records cover one link; without it every link of the document is included. A very long answer is cut at a whole record and gives a `continue_from` value for the remaining rows. The website file itself holds only the oldest 5,000 reads of a document or link, and the result says when it is every row of that file and when the file is capped. It changes nothing. It is the full export; get_share_activity summarises one link. (read-only)
- `replace_document`: Replaces the contents of a document already on HTMLRadar, which is how a page that has been sent is updated. Every existing link stays exactly as it is (same address, same settings, same reading history) and serves the new contents from the next time it is opened, so nobody is sent a second link; a link that is switched off or past its end date stays closed. The new HTML is screened for phishing signals as every upload is, and readers of a page the screen holds see that it is not available yet. The previous version stays listed in the document's version history on the website. There is no restore, from Claude or on the website; going back means replacing the contents again with the earlier page. Recipients may already have read the old contents. The call needs `expected_version`, the version get_document or list_documents shows, so a newer version is never overwritten. The tool accepts either the whole new page in `html`, up to 5 MB with its images as references, or `edits`: pieces of text to find in the page get_document returned, each with its replacement and each appearing exactly once. Past 5 MB, only `edits` work, because only the changes travel. A change to a page already on HTMLRadar is made by reading it with get_document and sending back the edited short form, or only the `edits`: that works for pages up to 30 MB, the same limit as the website, and keeps every image; a whole new file is needed only to replace the page itself. A page with more than 20 MB of text and code besides its images cannot be read or changed here, and a change that would take a page past that is refused, so nothing is stored. Images that need a login, expiring image addresses and local file paths do not load for readers of the link; an image embedded in the HTML as a data URI travels inside the page. The tool does not check that images load. On an update, embedded PNG, JPEG, GIF and WebP images appear as short htmlradar-image references in the document contents. Unchanged references restore the original images, so only new images count towards the 5 MB limit. Other embedded images, such as SVG, stay in the markup and count towards it.
- `get_document`: Returns the current contents of a document on HTMLRadar so they can be changed and put back with replace_document. A change to a page already on HTMLRadar is made this way, for pages up to 30 MB, the same limit as the website: read the page here, then send the edited short form, or only the changes, to replace_document; a whole new file is needed only to replace the page itself. Each embedded PNG, JPEG, GIF and WebP image appears as a short htmlradar-image reference instead of its data; unchanged references restore the original images, and other embedded images, such as SVG, stay in the markup. Up to 5 MB of text and code, with its images as references, the whole page comes back. Between 5 MB and 20 MB it is too large to return whole: pass `query`, a word or phrase from the part to change, and it returns up to 20 passages where that text appears, exact text for `edits`. Over 20 MB of text and code besides its images, the page cannot be read or changed here. A document served from its own address has no stored contents to return. It reads only this account's documents and changes nothing. (read-only)
- `whoami`: Reports which HTMLRadar account the API key belongs to (its email address), the plan it is on and how many of its free tracked links it has used out of the free allowance, or that tracked links are unlimited. It also reports what this connection may do (read only, or read and publish), any notice about the plan, and any notice about a newer version of the HTMLRadar package. (read-only)
- `get_page_guidelines`: Returns HTMLRadar's guidelines for pages that read well on phones and give accurate section reading times. It reads no account data and changes nothing. (read-only)

## FAQ

### How do I connect HTMLRadar to my agent?

You can connect via the Claude Code plugin, by adding the remote MCP URL to Claude Desktop or Cursor, or by using an API key with the npx htmlradar-mcp package.

### Do readers need an account to view my shared pages?

No, readers do not need to create an account or install any software to view the content.

### Can I update a document without changing the link?

Yes, you can use the replace_document tool to put new content behind existing links.

### What kind of reading data can I track?

You can see who opened a link, how long they read, how far they scrolled, and which specific sections they spent time on.
