Zactonz

Zactonz MCP サーバー

Zactonz API用のModel Context Protocolサーバーです。AI アシスタントがウェブページのスクリーンショットを撮影したり、ページを Markdown として読み取ったり、リンクをプレビューしたり、DNS、SSL、WHOIS レコードを検索したり、ドメインのメール設定を確認したり、メールアドレスを検証したり、QR コード、バーコード、ソーシャルカード画像を生成したり、画像を変換したり、テキストを翻訳したりできます。

お使いのマシン上で 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

インストールはこれで完了です。実行時の依存関係は 2 つだけで、ビルド手順はありません。起動することを確認してください。入力を待つため、終了するには 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. ZACTONZ_API_KEYSにキーをカンマ区切りで指定して、サーバーをMCPクライアントに追加します。

ソースから実行した場合は、以下のnpx形式の代わりに、そこで示した"command"と"args"を指定してください。

Claude Desktop、Cursor、Windsurf など、mcpServersブロックを読み取るクライアントの場合：

{
  "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にのみ送信され、それ以外に送信されることはありません。また、アシスタントに返される内容に含まれることもありません。

ツール

ツール	用途	キー
capture_screenshot	Web ページを画像または PDF としてキャプチャします	screen
render_html	HTML を画像または PDF にレンダリングします	screen
read_webpage	Web ページを 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 に各ツールの引数が記載されています。

接続後のリクエスト例：

• 「390 ピクセル幅の画面で example.com のスクリーンショットを撮り、メニューが収まっているか教えてください。」
• 「https://example.com/pricing を読み、各プランを要約してください。」
• 「example.com の SPF と DMARC は正しく設定されていますか？」
• 「example.com の SSL 証明書はいつ期限切れになりますか？」

結果

ツールは JSON テキストを返します。生の API とは次の 2 点が異なります。

• read_webpage と convert_html_to_markdown は Markdown をプレーンテキストとして返し、その後に残りのフィールドを JSON として返します。アシスタントから追加の指定がない限り、最大 20,000 文字まで取得します。
• 画像を生成するツールはリンクを返します。ファイルが 750 KB 以下の場合は画像も返すため、アシスタントが確認できます。capture_screenshot と render_html は、指定がない限りサイズを抑えるために JPEG 品質 80 を使用します。PDF と 750 KB を超える画像はリンクのみ返されます。

拒否された呼び出しはツールエラーとして返され、API のメッセージ、ステータス、制限に達した場合の待機時間、およびリクエスト ID が含まれます。

制限と所要時間

呼び出しでは、直接 API を呼び出す場合と同様に、プランのクォータからユニットが消費されます。レート制限とクォータをご覧ください。

MCP クライアントが 60 秒後に待機を終了するため、ツール呼び出しには合計 55 秒が割り当てられます。この時間内にサーバーは 1 回だけ再試行します。再試行によって作業が重複しない場合に限り、短い 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、QR コード、バーコード、変換された画像は、各エンドポイントのリファレンスページに記載された期間、推測困難な URL で api.zactonz.com に保存されます。非公開にしておく必要があるドキュメントをレンダリングしないでください。
• 送信されるデータ。 ツールの引数は api.zactonz.com に送信され、それ以外には送信されません。サーバーはログを保持せず、ディスクにも何も保存しません。API 側でのデータの取り扱いについては、プライバシーポリシーをご覧ください。
• 引数は検証されます。 リクエストを行う前に各ツールのスキーマに照らして検証され、スキーマに含まれない引数は拒否されます。
• インライン表示用に画像を取得するのは、API 自身のホストからのみです。 HTTPS を使用し、リダイレクトには従いません。
• URL を取得するツールは Zactonz のサーバーから取得し、プライベートアドレスと内部アドレスは拒否されます。

脆弱性の報告については、SECURITY.mdの説明をご覧ください。

トラブルシューティング

• ツールが見つからない。 キーがあるツールのみが一覧表示されます。その製品のキーを追加し、クライアントを再起動してください。
• すべての呼び出しに設定手順が返される。 ZACTONZ_API_KEYS が空であるか、有効なキーが含まれていません。サーバーは理由を stderr に出力します。ほとんどのクライアントでは、MCP ログに表示されます。
• 「Missing or invalid API key.」 キーが失効しているか、入力に誤りがあります。アシスタントに check_api_key を実行させるか、コンソールでキーを確認してください。
• スクリーンショットにインライン画像が表示されない。 ファイルがインライン表示の上限を超えています。画質またはサイズを下げるか、ZACTONZ_MCP_INLINE_IMAGE_BYTES の値を大きくしてください。

バージョニング

このパッケージはセマンティックバージョニングに従います。0.x の間は、マイナーリリースでツール名や引数名が変更される場合があります。こうした変更は変更履歴に記載されます。

開発

CONTRIBUTING.mdをご覧ください。

ライセンス

MIT。LICENSEをご覧ください。Zactonz Technologiesがメンテナンスしています。