# Zactonz MCP Server

> A Model Context Protocol server that gives AI assistants the Zactonz APIs as tools: screenshots, page to Markdown, link previews, DNS, SSL, WHOIS, email checks, QR codes, barcodes, social images, image conversion and translation.

- **Type:** MCP server (SDKs & tools)
- **Version:** 0.1.0, released 6 Oct 2026
- **Requires:** Node.js 18+, An MCP client over stdio, Zactonz API keys
- **Licence:** MIT
- **Source:** https://github.com/zactonz/zactonz-mcp
- **Documentation:** https://developers.zactonz.com/tools/zactonz-mcp/

## Overview

The Zactonz MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io) server for the Zactonz APIs. Connect it to an MCP client such as Claude Desktop, Claude Code, Cursor, Windsurf or VS Code, and the assistant can capture a screenshot of a web page, read a page as Markdown, preview a link, look up DNS, SSL and WHOIS records, check a domain's email setup, verify addresses, generate QR codes, barcodes and social card images, convert images and translate text.

It runs on your machine over stdio and needs Node.js 18 or newer. Keys stay in the server process and are sent to `api.zactonz.com` and nowhere else.

### What the assistant can do

Once connected, requests like these work as you would expect:

- "Take a screenshot of example.com on a 390 pixel wide screen and tell me whether the menu fits."
- "Read https://example.com/pricing and summarise the plans."
- "Does example.com have SPF and DMARC set up correctly?"
- "When does the SSL certificate for example.com expire?"
- "Make a QR code for our contact page."

### How it fits together

- **Eighteen tools, one per API operation**, named for what they do: `capture_screenshot`, `read_webpage`, `lookup_dns`, `generate_qr_code` and so on, plus `check_api_key` for plan and quota. The [Tools](https://developers.zactonz.com/tools/zactonz-mcp/tools/) tab lists them all.
- **Generated from the API specifications** that also produce this portal's reference pages, so argument names and descriptions match the API.
- **Only the tools you have keys for are offered.** A Zactonz key works for one product, and the server reads the product from the key, so an assistant never sees a tool it cannot call.
- **Arguments are validated** against each tool's schema before any request leaves the machine.
- **Images come back inline** when they are small enough for the assistant to look at, and as a link otherwise.
- **Cancellation is honoured**, and a call never outlives the client's own timeout.

### Requirements

Node.js 18 or newer, an MCP client that speaks stdio, and one or more API keys from the [console](https://developers.zactonz.com/console/). There is a free plan.

### Versioning

The package follows semantic versioning. While it is at `0.x`, a minor release may rename a tool or an argument; such changes are listed in the [changelog](https://github.com/zactonz/zactonz-mcp/blob/main/CHANGELOG.md). The server is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/?search=zactonz) as `io.github.zactonz/zactonz-mcp`, so clients that browse the registry can add it from there.

## Setup

### 1. Create API keys

Create a key for each product you want the assistant to use in the [API console](https://developers.zactonz.com/console/). A key works for one product, and the product is part of the key: `zk_screen_…` is a screenshot key, `zk_markdown_…` a Markdown key. Put every key you have in `ZACTONZ_API_KEYS`, separated by commas. The server uses the right one for each call and offers the assistant only the tools those keys can call.

### 2. Add the server to your client

The server is published on npm as [@zactonz/mcp](https://www.npmjs.com/package/@zactonz/mcp) and is run with `npx`, so there is nothing to install by hand.

Clients that read an `mcpServers` block, such as Claude Desktop, Cursor and Windsurf:

```json
{
  "mcpServers": {
    "zactonz": {
      "command": "npx",
      "args": ["-y", "@zactonz/mcp"],
      "env": {
        "ZACTONZ_API_KEYS": "zk_screen_…,zk_markdown_…,zk_domain_…"
      }
    }
  }
}
```

VS Code, in `.vscode/mcp.json`:

```json
{
  "servers": {
    "zactonz": {
      "command": "npx",
      "args": ["-y", "@zactonz/mcp"],
      "env": { "ZACTONZ_API_KEYS": "zk_screen_…,zk_markdown_…" }
    }
  }
}
```

Claude Code:

```bash
claude mcp add zactonz --env ZACTONZ_API_KEYS="zk_screen_…,zk_markdown_…" -- npx -y @zactonz/mcp
```

On Windows, if the client cannot start `npx` directly, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@zactonz/mcp"]`.

The first start downloads the package and its two dependencies; later starts are immediate. To pin a commit or run without a registry, the repository's README describes running from source.

### 3. Check it works

Ask the assistant to run `check_api_key`. It reports the plan and the quota remaining for each key. Without any valid key the server still starts and lists every tool, and each call answers with these setup instructions.

### Configuration

| Variable | Purpose | Default |
|---|---|---|
| `ZACTONZ_API_KEYS` | API keys, separated by commas | none |
| `ZACTONZ_MCP_INLINE_IMAGE_BYTES` | Largest image returned inline, in bytes. `0` returns links only | `750000` |
| `ZACTONZ_BASE_URL` | API base URL | `https://api.zactonz.com` |

Values in `ZACTONZ_API_KEYS` that are not Zactonz keys are ignored and reported on stderr, with the value masked, rather than guessed at.

### Troubleshooting

- **A tool is missing.** Only tools with a key are listed. Add a key for that product and restart the client.
- **Every call answers with setup instructions.** `ZACTONZ_API_KEYS` is empty or holds no valid key. The server prints the reason on stderr, which most clients show in their MCP log.
- **"Missing or invalid API key."** The key was revoked or mistyped. Ask the assistant to run `check_api_key`, or check the key in the console.
- **A screenshot has no inline image.** The file is over the inline limit. Lower the quality or size, or raise `ZACTONZ_MCP_INLINE_IMAGE_BYTES`.

## Tools

A tool is offered to the assistant only when a key for its product is configured. The argument list of each tool is in the [tools reference](https://github.com/zactonz/zactonz-mcp/blob/main/docs/tools.md) on GitHub; the full behaviour of the endpoint behind it is on the linked API page.

| Tool | Purpose | API | Key |
|---|---|---|---|
| `capture_screenshot` | Capture a web page as an image or PDF | [Screenshot (URL)](https://developers.zactonz.com/apis/screenshot-url/) | `screen` |
| `render_html` | Render HTML to an image or PDF | [Screenshot (HTML)](https://developers.zactonz.com/apis/screenshot-html/) | `screen` |
| `read_webpage` | Read a web page as Markdown | [Web Page to Markdown](https://developers.zactonz.com/apis/markdown/) | `markdown` |
| `convert_html_to_markdown` | Convert HTML to Markdown | [Web Page to Markdown](https://developers.zactonz.com/apis/markdown/) | `markdown` |
| `preview_link` | Title, description, image and metadata of a URL | [Link Preview](https://developers.zactonz.com/apis/link-preview/) | `unfurl` |
| `lookup_dns` | DNS records and DNSSEC status | [DNS Lookup](https://developers.zactonz.com/apis/domain-dns/) | `domain` |
| `inspect_ssl_certificate` | Certificate, chain, expiry and TLS details | [SSL Inspector](https://developers.zactonz.com/apis/domain-ssl/) | `domain` |
| `lookup_whois` | Registrar, dates and nameservers of a domain | [WHOIS](https://developers.zactonz.com/apis/domain-whois/) | `domain` |
| `check_email_domain` | MX, SPF, DKIM, DMARC and related records, scored | [Domain Email Health](https://developers.zactonz.com/apis/email-domain/) | `email` |
| `verify_emails` | Whether addresses can receive mail | [Mail Verifier](https://developers.zactonz.com/apis/mail-verifier/) | `mverifier` |
| `generate_qr_code` | Generate a QR code | [QR Encoder](https://developers.zactonz.com/apis/qr-encoder/) | `qr` |
| `read_qr_code` | Decode a QR code | [QR Decoder](https://developers.zactonz.com/apis/qr-decoder/) | `qr` |
| `generate_barcode` | Generate a barcode | [Barcode Encoder](https://developers.zactonz.com/apis/barcode-encoder/) | `barcode` |
| `generate_social_image` | Generate an Open Graph image | [OG Image](https://developers.zactonz.com/apis/og-image/) | `og` |
| `convert_image` | Convert, resize or crop an image | [Image Convert](https://developers.zactonz.com/apis/image-convert/) | `image` |
| `inspect_image` | Dimensions, format and colours of an image | [Image Convert](https://developers.zactonz.com/apis/image-convert/) | `image` |
| `translate_text` | Translate between 46 languages | [Translator](https://developers.zactonz.com/apis/translator/) | `translator` |
| `get_drive_download_link` | Direct download link for a Google Drive file | [Google Drive Direct Link](https://developers.zactonz.com/apis/gdrive-direct-link/) | `gdrive` |
| `check_api_key` | Plan and remaining quota of a key | key check | any |

### Results

A tool returns JSON text. Two things differ from the raw API:

- `read_webpage` and `convert_html_to_markdown` return the Markdown as plain text, followed by the remaining fields as JSON. They request at most 20,000 characters unless the assistant asks for more.
- A tool that produces an image returns the link and, when the file is 750 KB or smaller, the image itself, so the assistant can look at it. `capture_screenshot` and `render_html` use JPEG quality 80 unless told otherwise, to stay under that size. PDFs and larger images come back as a link only.

A refused call is returned as a tool error carrying the API's message, the status, how long to wait when a limit was reached, and the request id.

## Security & limits

### What is sent and kept

- **Tool arguments go to `api.zactonz.com` and nowhere else.** The server keeps no logs and stores nothing on disk. The API's own handling of data is covered by the [privacy policy](https://zactonz.com/privacy/).
- **Keys stay in the server process.** They are sent only in the `Authorization` header to the API and are never included in anything returned to the assistant.
- **Arguments are validated** against each tool's schema before any request is made, and arguments outside the schema are refused.
- **Images are fetched for inline display only from the API's own host**, over HTTPS, without following redirects, and capped in size while streaming.
- **Tools that fetch a URL do so from Zactonz's servers**, which refuse private and internal addresses.

### Untrusted content

`read_webpage`, `preview_link` and `read_qr_code` return text written by whoever controls the page or the code. That text can contain instructions aimed at the assistant. The server labels it as third-party data, but the label is advice to the model, not a guarantee. Review what an assistant does after reading pages you do not control.

### Generated files are public links

Screenshots, PDFs, QR codes, barcodes and converted images are stored on `api.zactonz.com` at unguessable URLs that anyone holding the link can open, for the period given on each endpoint's reference page. Do not render documents that must stay private.

### Timing and quota

Calls spend units from your plan's quota, the same as direct API calls. See [rate limits and quotas](https://developers.zactonz.com/apis/rate-limits/).

A tool call is given 55 seconds in total, because MCP clients stop waiting after 60. Within that time the server retries once, and only where a retry cannot repeat work: after a `429` with a short `Retry-After`, after a gateway error on a read, or ten seconds after the API host's request burst guard rejects a call. If the client cancels a call, the server stops.

### Reporting a problem

Bugs and feature requests go to the [issue tracker](https://github.com/zactonz/zactonz-mcp/issues). Report a vulnerability privately by email as described in the repository's [security policy](https://github.com/zactonz/zactonz-mcp/blob/main/SECURITY.md); do not open a public issue for it.