Zactonz

Zactonz MCP 服务

一个面向 Zactonz API 的 Model Context Protocol 服务。它可让 AI 助手截取网页屏幕截图、将网页读取为 Markdown、预览链接、查询 DNS、SSL 和 WHOIS 记录、检查域名的电子邮件配置、验证电子邮件地址、生成二维码、条形码和社交卡片图片、转换图片以及翻译文本。

它通过 stdio 在你的计算机上运行，需要 Node.js 18 或更高版本。

安装

无需预先安装任何内容。下方的客户端配置会运行 npx -y @zactonz/mcp，首次使用时会获取该软件包，并将其缓存。你需要 Node.js 18 或更高版本。

除非你想从检出目录运行，否则请跳至设置。

从源代码安装

适用于固定到特定提交、开发服务或不通过软件包注册表运行的情况。 需要 Node.js 18 或更高版本以及 git。

git clone https://github.com/zactonz/zactonz-mcp.git
cd zactonz-mcp
npm ci --omit=dev

安装就这么简单：两个运行时依赖，无需构建。检查它是否能启动——它会等待输入，因此按 Ctrl+C 退出：

node bin/zactonz-mcp.js

然后将客户端指向绝对路径，以替换下文使用的 npx 形式：

{
  "mcpServers": {
    "zactonz": {
      "command": "node",
      "args": ["/absolute/path/to/zactonz-mcp/bin/zactonz-mcp.js"],
      "env": {
        "ZACTONZ_API_KEYS": "zk_screen_…,zk_markdown_…"
      }
    }
  }
}

请使用真正的绝对路径——大多数客户端不会展开 ~ 和相对路径。在 Windows 上，请使用正斜杠或转义后的反斜杠，例如 C:/Users/you/zactonz-mcp/bin/zactonz-mcp.js。

对于 Claude Code：

claude mcp add zactonz --env ZACTONZ_API_KEYS="zk_screen_…" -- node /absolute/path/to/zactonz-mcp/bin/zactonz-mcp.js

如果你希望将 zactonz-mcp 添加到 PATH，请在克隆目录中运行 npm link，然后使用 "command": "zactonz-mcp"，不带 args。

之后更新时：git pull && npm ci --omit=dev。

设置

1. 在 API 控制台中为你想使用的每款产品创建一个密钥。该服务提供免费套餐。
2. 将服务添加到你的 MCP 客户端，并在 ZACTONZ_API_KEYS 中填入密钥，各密钥之间用逗号分隔。

如果你是从源代码安装，请将下方 npx 形式替换为其中显示的 "command" 和 "args"。

读取 mcpServers 配置块的客户端，例如 Claude Desktop、Cursor 和 Windsurf：

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

VS Code（.vscode/mcp.json）：

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

Claude Code：

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

在 Windows 上，如果客户端无法直接启动 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@zactonz/mcp"]。

密钥

一个 Zactonz 密钥对应一款产品，密钥中包含产品标识：zk_screen_… 是屏幕截图密钥，zk_markdown_… 是 Markdown 密钥。请将你拥有的所有密钥放入 ZACTONZ_API_KEYS。服务会在每次调用时使用对应的密钥，并且只向助手提供这些密钥允许调用的工具。

密钥会保留在服务进程中。它们只会通过 Authorization 标头发送到 api.zactonz.com，不会发送到其他任何地方，也绝不会包含在返回给助手的内容中。

工具

工具	用途	Key
capture_screenshot	将网页截取为图像或 PDF	screen
render_html	将 HTML 渲染为图像或 PDF	screen
read_webpage	将网页读取为 Markdown	markdown
convert_html_to_markdown	将 HTML 转换为 Markdown	markdown
preview_link	URL 的标题、描述、图像和元数据	unfurl
lookup_dns	DNS 记录和 DNSSEC 状态	domain
inspect_ssl_certificate	证书、证书链、有效期和 TLS 详情	domain
lookup_whois	域名的注册商、日期和名称服务器	domain
check_email_domain	MX、SPF、DKIM、DMARC 及相关记录，并给出评分	email
verify_emails	邮箱地址是否可以接收邮件	mverifier
generate_qr_code	生成 QR 码	qr
read_qr_code	解码 QR 码	qr
generate_barcode	生成条形码	barcode
generate_social_image	生成 Open Graph 图像	og
convert_image	转换、调整大小或裁剪图像	image
inspect_image	图像的尺寸、格式和颜色	image
translate_text	在 46 种语言之间翻译	translator
get_drive_download_link	获取 Google Drive 文件的直接下载链接	gdrive
check_api_key	查询密钥的套餐和剩余配额	any

docs/tools.md 列出了每个工具的参数。

连接后可尝试以下请求：

• “截取 example.com 在宽度为 390 像素的屏幕上的页面，并告诉我菜单是否能完整显示。”
• “读取 https://example.com/pricing 并总结各个套餐。”
• “example.com 是否正确设置了 SPF 和 DMARC？”
• “example.com 的 SSL 证书何时到期？”

结果

工具会返回 JSON 文本。与原始 API 相比，有两点不同：

• read_webpage 和 convert_html_to_markdown 会先以纯文本形式返回 Markdown，再以 JSON 形式返回其余字段。除非助手要求更多内容，否则它们最多请求 20,000 个字符。
• 生成图像的工具会返回链接；如果文件不超过 750 KB，也会同时返回图像，供助手查看。除非另有说明，capture_screenshot 和 render_html 使用 80 的 JPEG 质量，以确保文件低于该大小。PDF 和较大的图像仅以链接形式返回。

被拒绝的调用会以工具错误的形式返回，其中包含 API 的消息、状态、达到限额时需要等待的时间，以及请求 ID。

限制和时限

调用会消耗套餐配额中的单位，与直接调用 API 相同。请参阅速率限制和配额。

每次工具调用的总时限为 55 秒，因为 MCP 客户端会在 60 秒后停止等待。在此期间，服务会重试一次，且仅在不会重复执行工作的情况下重试：收到带有较短 Retry-After 的 429 响应后、读取操作遇到网关错误后，或 API 的请求突发限制拒绝调用 10 秒后。如果客户端取消调用，服务就会停止。

配置

变量	用途	默认值
ZACTONZ_API_KEYS	API 密钥，以逗号分隔	无
ZACTONZ_MCP_INLINE_IMAGE_BYTES	内联返回的最大图片大小（字节）。0 表示仅返回链接	750000
ZACTONZ_BASE_URL	API 基础 URL	https://api.zactonz.com

即使没有密钥，服务仍会启动并列出所有工具，每次调用都会返回设置说明。ZACTONZ_API_KEYS 中不是 Zactonz 密钥的值会被忽略，并在 stderr 中报告。

安全与隐私

• 不可信内容。 read_webpage、preview_link 和 read_qr_code 会返回由网页或代码控制者编写的文本。这些文本可能包含针对助手的指令。服务会将其标记为第三方数据，但该标记只是对模型的提示，并非保证。阅读你无法控制的网页后，请检查助手的操作。
• 生成的文件是公开链接。 截图、PDF、二维码、条形码和转换后的图片会存储在 api.zactonz.com 上，使用无法猜测的 URL，任何持有链接的人都可以在各端点参考页面所列的期限内打开。请勿渲染必须保密的文档。
• 发送的内容。 工具参数只会发送到 api.zactonz.com，不会发送到其他地方。服务不保留日志，也不会在磁盘上存储任何内容。API 对数据的处理方式详见隐私政策。
• 参数会在发出任何请求前根据各工具的架构进行验证，架构之外的参数会被拒绝。
• 仅从 API 自己的主机通过 HTTPS 获取图片以供内联显示，且不会跟随重定向。
• 从 URL 获取内容的工具会通过 Zactonz 的服务器执行，该服务器会拒绝私有和内部地址。

如需报告漏洞，请参阅 SECURITY.md。

故障排除

• 缺少某个工具。 仅列出拥有密钥的工具。为该产品添加密钥并重启客户端。
• 每次调用都返回设置说明。 ZACTONZ_API_KEYS 为空或不包含有效密钥。服务会在 stderr 中打印原因，大多数客户端会在其 MCP 日志中显示该信息。
• “缺少或无效的 API 密钥。” 密钥已被撤销或输入错误。请让助手运行 check_api_key，或在控制台中检查密钥。
• 截图没有内联图片。 文件超过了内联限制。请降低质量或尺寸，或调高 ZACTONZ_MCP_INLINE_IMAGE_BYTES。

版本管理

此软件包遵循语义化版本。处于 0.x 版本期间，次要版本可能会重命名工具或参数；此类变更会列在变更日志中。

开发

请参阅 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。由 Zactonz Technologies 维护。