zola-mcp

Zola MCP

Claude を Zola に接続する Model Context Protocol サーバーです。結婚式の業者、予算、ゲストリスト、席次表、イベント、ギフト登録、問い合わせなどに自然言語でアクセスできます。

警告

AI によって開発されたプロジェクトです。 このコードベースはすべて Claude Code によって構築され、現在も積極的に保守されています。実装を監査した人間はいません。使用前に、すべてのコードとツールの権限を確認してください。

できること

Claude に次のようなことを尋ねられます。

• 「結婚式の準備はどんな感じ？」
• 「ノースカロライナ州シャーロットの写真家を探して」
• 「会場費を 25,000 ドルに更新して」
• 「まだ出欠の返事をしていないのは誰？」
• 「Pat をテーブル 1 に座らせて」
• 「新しい業者からのメッセージはある？」
• 「いとこの Mike をゲストリストに追加して」
• 「ギフトトラッカーを見せて」

必要条件

• Claude Desktop または Claude Code
• Node.js 22 以降
• Zola アカウント
• env var を使わない方法の場合：ContextMint Bridge Chrome 拡張機能（Safari はまだ利用できません。現時点では Chrome を使用してください）

利用規約への同意

この MCP サーバーを使用することで、以下の事項を認識し、同意したものとみなされます。

1. このサーバーがアクセスするのは、ご自身の Zola アカウントです。 認証にはご自身の認証情報を使用します。他の人の結婚式ウェブサイト、ギフト登録、ゲストリストにアクセスすることはなく、またアクセスできません。

2. このサーバーの使用には Zola の利用規約が適用されます。zola.com を直接利用する場合と同様です。ここで特に関連する条項は次のとおりです。

[利用者は]、あらゆる情報を密かに傍受またはその他の方法で取得することを目的としたハードウェアまたはソフトウェアを使用してはなりません。これには、「スクレイピング」その他のデータマイニング手法、ロボット、または類似のデータ収集・抽出ツールの使用が含まれますが、これらに限定されません。

また、エージェントが利用者に代わって操作する点について、特に重要な条項があります。「お客様は、アカウントとパスワードの機密性を維持する責任を負います。…お客様は、認定代理人またはその他の第三者が行った場合であっても、お客様のアカウントとパスワードを使用して行われるすべての活動について、全責任を負うことに同意します。」

このサーバーでツールを呼び出すたびに、利用者はこれらの規約に同意することになります。保守担当者が 2026-05-23 に確認した内容です。Zola の利用規約は明確です。この MCP が利用者の認定代理人として動作する場合、その行為は利用者自身の行為とみなされます。

3. 個人利用のみとし、商用利用はできません。 このプロジェクトは Zola, Inc. とは無関係であり、同社の承認、支援、後援を受けておらず、提携もしていません。カップルが自身の結婚式ウェブサイト、ギフト登録、業者の調査、ゲストリストを管理するための個人用自動化ツールです。Zola の業者ディレクトリの一括抽出、ギフト登録のスクレイピング、Zola との競合を目的とした使用は禁止されています。

4. 安定性は保証されません。 このサーバーは、予告なく変更される可能性のある Zola の内部エンドポイントを呼び出す場合があります。動作しなくなる可能性があります。

5. このサーバーを Zola アカウントに関連して使用したことによる結果については、利用者が全責任を負います。 これには、レート制限、アカウントへの警告、アカウント停止、その他の措置が含まれます。Zola の利用規約に従い、この MCP が利用者のアカウントで行うことは、すべて利用者自身の行為です。確定する前に、ゲストリストの編集、ギフト登録の変更、問い合わせを確認してください。Zola から使用について異議を申し立てられた場合は、このサーバーの使用を中止してください。

このセクションは、保守担当者が誠意をもってまとめた利用規約の要約です。法的助言ではなく、Zola の実際の利用規約を変更または無効にするものではありません。

インストール

オプション A — MCPB（推奨）

Releasesから最新の.mcpbバンドルをダウンロードして、インストールします。

claude mcp add-from-mcpb zola-mcp-x.y.z.mcpb

ZOLA_REFRESH_TOKENの入力を求められます（下記のリフレッシュトークンの取得を参照）。

オプション B — npm

npx -y zola-mcp

Claudeの設定（.mcp.jsonまたはClaude Desktopの設定）に追加します。

{
  "mcpServers": {
    "zola": {
      "command": "npx",
      "args": ["-y", "zola-mcp"],
      "env": {
        "ZOLA_REFRESH_TOKEN": "your-refresh-token-jwt"
      }
    }
  }
}

オプション C — ソースから

git clone https://github.com/chrischall/zola-mcp.git
cd zola-mcp
npm install
npm run build

Claude Desktopの設定に追加します。

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zola": {
      "command": "node",
      "args": ["/absolute/path/to/zola-mcp/dist/bundle.js"],
      "env": {
        "ZOLA_REFRESH_TOKEN": "your-refresh-token-jwt"
      }
    }
  }
}

リフレッシュトークンの取得

方法は2つあります。どちらも同じusr Cookieの値を取得できます。これは約1年間有効なJWTで、リフレッシュトークンとしても機能します。

オプション A — ContextMint Bridge（推奨）

1. ContextMint Bridgeをインストールします。Chromeの場合は、最新リリースからChrome用のZIPファイルをダウンロードして解凍し、chrome://extensionsで展開済みの拡張機能として読み込みます（デベロッパーモードをオンにします）。Safariにはまだ対応していません（一般公開されていないContextMintアプリに同梱される予定です）。現時点ではChromeを使用してください。

   ContextMint Bridgeは、同じメンテナーによる、名称を変更したfetchproxyのブラウザー拡張機能です。fetchproxyのREADME（fetchproxy#extension）からも参照されています。ソースはnullnet-app/contextmint-bridgeで公開されています。ご自身でビルドするか、リリースのZIPファイルと、その隣に公開されている.sha256ファイルを照合してください（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

2. そのブラウザーでzola.com/account/loginにサインインします。

3. Claudeの設定でZOLA_REFRESH_TOKENを設定しないでください。

最初のツール呼び出し時に、MCPはchrome.cookies.getを使って拡張機能からHttpOnlyのusr Cookieを取得し、その後はNodeからAPIに直接アクセスします。ブリッジが実行時の処理経路に入ることはありません。

このCookieは約1年間有効なリフレッシュトークンであるため、$MCP_DATA_DIR/.zola-mcp/refresh-token.jsonにキャッシュされます（$HOMEにフォールバックし、パーミッションは0600です）。以降の起動時にはこのファイルから読み込むため、ブラウザーは不要です。そのため、ブラウザーがないリモートホストでもサーバーを使用できます。APIがキャッシュ済みトークンを拒否した場合（サインアウトした場合、または有効期限の1年を過ぎた場合）は、自動的に破棄され、拡張機能に再取得を要求します。再認証するには、zola.comに再度サインインしてください。ディスクに何も保存せず、毎回ブラウザーに要求するには、ZOLA_TOKEN_CACHE=falseを設定します。

ZOLA_DISABLE_FETCHPROXY=1を設定すると、このフォールバックを無効にできます（拡張機能を利用できないヘッドレス環境やCI環境など）。

オプション B — 手動（DevTools）

1. 任意のブラウザーでzola.com/account/loginにサインインします。
2. DevToolsを開き、Application → Cookies → https://www.zola.comの順に選択します。
3. usr Cookieの値をコピーします。
4. .envにZOLA_REFRESH_TOKEN=<value>として貼り付けます（またはClaudeの設定のenvブロックに貼り付けます）。

Claude Desktopを再起動する

完全に終了して（MacではCmd+Q）、再度起動します。

確認

Claudeに「結婚式の準備はどう？」と尋ねます。結婚式のダッシュボードが表示されるはずです。

認証情報

環境変数	必須	備考
ZOLA_REFRESH_TOKEN	条件付き	リフレッシュトークン JWT（有効期間は約1年）。未設定の場合、MCP は ContextMint Bridge ブラウザー拡張機能にフォールバックし、サインイン済みの zola.com タブから usr Cookie を読み取ります。
ZOLA_DISABLE_FETCHPROXY	いいえ	1 に設定すると、fetchproxy フォールバックを無効にします（ヘッドレス／CI）。トークンキャッシュは無効になりません。ヘッドレス実行でも、以前のブートストラップでキャッシュされたトークンを再利用できます。ファイルの読み取りはブラウザーを開くことではないためです。
ZOLA_TOKEN_CACHE	いいえ	false に設定すると、ディスク上のリフレッシュトークンキャッシュを無効にし、起動のたびにブラウザーへ問い合わせます。デフォルトでは有効で、ZOLA_REFRESH_TOKEN が設定されている場合は機能しません。
ZOLA_TOKEN_FILE	いいえ	キャッシュファイルの絶対パスです。デフォルトは $MCP_DATA_DIR/.zola-mcp/refresh-token.json、それがない場合は $HOME/.zola-mcp/refresh-token.json です。
ZOLA_ACCOUNT_ID	いいえ	初回使用時に API から自動解決されます
ZOLA_REGISTRY_ID	いいえ	初回使用時に API から自動解決されます
MCP_CONFIRM_MODE	いいえ	デフォルトは ask-user です。確認が必要な書き込みを、確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で実行する際の動作です。ask-user：2段階で実行します。最初の呼び出しでは何も書き込まず、プレビューとトークンを返します。モデルは、トークンを使って再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく2段階で実行しますが、モデルはプレビューを確認した後、自らトークンを使用できます。refuse：このようなクライアントでは書き込みを拒否します。プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off でない限り、常に実際のプロンプトが表示されます。認識されない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	いいえ	デフォルトは on です。off にすると確認プロンプトは送信されず、すべてのクライアントで MCP_CONFIRM_MODE の動作になります。プロンプトを表示できると申告しているものの実際には表示しないクライアントでは、ゲート付きの呼び出しが停止するため、そのようなクライアントで設定してください（opencode 2.0.x）。それ以外の値では on のままとなり、stderr に警告が表示されます。
MCP_CONFIRM_TTL_SECONDS	いいえ	デフォルトは 600 です。確認トークンの有効期間です。
MCP_CONFIRM_SECRET	いいえ	確認トークンの署名キーです（デフォルト：プロセスごとにランダム）。サーバーの再起動後もトークンを有効にする必要がある場合に限り設定してください。

利用可能なツール

12の分野にわたる77個のツールがあります。「権限」列は、呼び出しによる変更の前に必要な操作を示します。

• 自動 — 読み取り専用です。確認なしで実行されます。
• ホストのプロンプト — 書き込み操作です。読み取り専用以外のツールの実行前にプロンプトを表示するクライアント（Claude Code、Claude Desktop）では、最初に確認を求めます。サーバー自体は確認しないため、プロンプトのないクライアント（claude.ai）では、最初の呼び出しで実行されます。
• サーバーゲート — 元に戻せない書き込み、またはゲストに表示される内容を変更する書き込みです。そのため、サーバーがすべてのクライアントで確認を行います。

サーバーゲート対象の書き込みは、remove_guest、update_event、update_wedding_settings、remove_faq、remove_home_section、remove_poi、remove_travel_item、remove_registry_item、set_event_guests、remove_event_invitation です（set_event_guests はゲストの招待を取り消す場合のみ）。最初に世帯、イベント、アイテム、またはページの内容と、変更内容の詳細を示すプレビューが表示されます（スラッグの変更では変更前後のウェブサイト URL、非公開またはパスコードで保護されたレジストリ上のアイテム、あるいはデフォルトコレクション以外のアイテムは、公開ページに名前が表示されないため ID で表示されます）。承認後にのみ処理が続行されます。上記の MCP_CONFIRM_MODE を参照してください。

ベンダー

ツール	機能	権限
list_vendors	予約済みのベンダーをすべて一覧表示	自動
search_vendors	名前／カテゴリでベンダーを検索	自動
add_vendor	新しいベンダーを予約	ホストのプロンプト
update_vendor	ベンダーの詳細を更新	ホストのプロンプト
remove_vendor	ベンダーの予約を取り消し	ホストのプロンプト

予算

ツール	機能	権限
get_budget	すべての項目を含む予算の概要	自動
update_budget_item	費用またはメモを更新	ホストのプロンプト

ゲスト

ツール	内容	権限
list_guests	ゲストグループを統計情報とともに一覧表示します。デフォルトでは名前、区分、RSVP の状況を表示し、view: "full" を指定すると住所、メールアドレス、電話番号も表示します	自動
add_guest	ゲストグループを追加します	ホストの確認
update_guest_address	郵送先住所を更新します	ホストの確認
remove_guest	ゲストグループを（RSVP と席も含めて）削除します	サーバーによる制限

座席

ツール	内容	権限
list_seating_charts	座席表を一覧表示します	自動
get_seating_chart	テーブル、席、着席者を含む座席表を取得します	自動
list_unseated_guests	まだ着席していないゲストを一覧表示します	自動
assign_seat	ゲストを席に割り当てます	ホストの確認

問い合わせ

ツール	内容	権限
list_inquiries	ベンダーへのすべての問い合わせをステータスとともに一覧表示します	自動
get_inquiry_conversation	会話のメッセージ全体を取得します	自動
mark_inquiry_read	既読にします	ホストの確認

イベントと RSVP

ツール	内容	権限
list_events	すべてのイベントを RSVP 数とともに一覧表示します	自動
track_rsvps	イベントごとの RSVP を追跡します	自動
get_gift_tracker	受け取った贈り物とお礼状の状況を取得します	自動
get_registry	レジストリのアイテムと、アイテムごとの購入状況（requested_qty、purchased_qty、marked_fulfilled、availability、inconsistent）を取得します。limit／offset でページ分割できます	自動
update_event	イベントの詳細を更新します	サーバーによる制限
set_event_guests	イベントに招待するゲストグループを一括で設定します	サーバーによる制限
invite_guest_to_event	個別のゲストまたはゲストグループをイベントに招待します（追加のみ。ほかのイベントには影響しません）	ホストの確認
remove_event_invitation	個別のゲストまたはゲストグループへのイベント招待を取り消します	サーバーによる制限

レジストリと贈り物

ツール	内容	権限
search_registry_products	レジストリの範囲内で、カテゴリ別に Zola の商品を閲覧します	自動
add_registry_item	商品（SKU を指定）をレジストリに追加します	ホストの確認
update_registry_item	既存のレジストリアイテムを更新します。すべてのフィールドを指定する必要があります（全項目を置き換えます）	ホストの確認
remove_registry_item	ゲストが購入するレジストリからアイテムを削除します	サーバーによる制限
reconcile_registry	レジストリと贈り物の追跡情報を照合します：DUPLICATE_RISK（履行済みとしてマークされていますが購入されておらず、まだ購入可能）、UNATTRIBUTED（注文情報なしで購入されているため、贈り主と金額が不明）、ORPHAN_ORDER、MATCHED	自動

ウェディングサイト — ページと設定

ツール	内容	権限
list_pages	ウェディングサイトのすべてのページを、ID、種類、表示順、公開設定、テーマ情報とともに一覧表示します	自動
set_page_hidden	ウェディングサイトのページを表示または非表示にします（例：招待状を送るまで RSVP ページを非表示にする）	ホストの確認
reorder_pages	ウェブサイトのナビゲーションでページの順序を変更します	ホストの確認
update_page	ページレベルのメタデータ（タイトル、紹介文、ナビゲーションタイトル、公開設定、レイアウトのカスタマイズ）を更新します	ホストの確認
get_wedding_settings	結婚式の基本設定（タイトル、URL スラッグ、パートナーの名前、日付、都市、ハッシュタグ、ゲスト数、検索での公開設定）を取得します	自動
update_wedding_settings	結婚式の基本設定を更新します	サーバーによる制限

結婚式ウェブサイト — コンテンツ（FAQ、ホーム、アクティビティ、旅行）

ツール	機能	権限
list_faqs	結婚式ウェブサイトのFAQをすべて一覧表示します	自動
add_faq	ウェブサイトのFAQページに新しいFAQ（質問と回答）を追加します	ホストの確認
update_faq	既存のFAQを更新します — 3つのフィールド（question、answer、display_order）すべてを指定する必要があります	ホストの確認
remove_faq	公開ウェブサイトからFAQを削除します	サーバーによる制御
list_home_sections	ウェブサイトのホームページにあるストーリーセクションを一覧表示します	自動
add_home_section	ホームページにストーリーセクション（タイトル＋サブタイトル＋説明ブロック）を追加します	ホストの確認
update_home_section	ホームページのストーリーセクションを更新します — すべてのフィールドを指定する必要があります	ホストの確認
remove_home_section	公開ホームページからストーリーセクションを削除します	サーバーによる制御
list_pois	「アクティビティ」ページの観光スポットを一覧表示します	自動
add_poi	「アクティビティ」ページに観光スポット（レストラン、名所など）を追加します	ホストの確認
update_poi	観光スポットを更新します	ホストの確認
remove_poi	公開「アクティビティ」ページから観光スポットを削除します	サーバーによる制御
list_travel_items	ウェブサイトの旅行ページに掲載されているホテル、航空便、交通手段を一覧表示します	自動
add_travel_item	旅行ページに旅行項目（ホテル、航空便、列車、車、バス）を追加します	ホストの確認
update_travel_item	旅行項目を更新します	ホストの確認
remove_travel_item	公開旅行ページから旅行項目を削除します	サーバーによる制御

結婚式ウェブサイト — テーマ

ツール	機能	権限
get_current_theme	現在選択されているウェブサイトのテーマ（キー、名前、スウォッチの色、レイアウトタイプ）を取得します	自動
get_website_customizations	現在のウェブサイトの色とフォント設定、および利用可能なフォントと色のオプションを取得します	自動
search_themes	利用可能な結婚式ウェブサイトのテーマカタログを閲覧します	自動
update_current_theme	結婚式ウェブサイトを別のテーマテンプレートに切り替えます	ホストの確認
update_website_customization	ウェブサイトの色とフォントを更新します	ホストの確認

招待状とセーブ・ザ・デート

ツール	機能	権限
list_card_projects	招待状／セーブ・ザ・デート／シャワー招待状の「カード」プロジェクト（紙またはデジタル）を一覧表示します	自動
get_card_project	招待状プロジェクトの詳細を取得します。すべてのカスタマイズ（招待状、封筒、RSVPカード、詳細カード）、用紙／色の選択肢、カスタマイズごとのページが含まれます	自動
validate_card_project	招待状プロジェクトを検証し、カスタマイズごとのテキストの収まり、画像、ゲストの宛名に関するエラーを報告します	自動
get_card_project_guests	招待状プロジェクトに割り当てられたゲストグループを一覧表示します。印刷する宛名のグループごとのフォントサイズ上書き設定も含まれます	自動
get_card_suite	招待状デザインの「スイート」（統一デザインの招待状、RSVPカード、詳細カードのセット）の詳細を取得します。用紙の種類、サイズ、価格帯が含まれます	自動
search_card_catalog	招待状デザインカタログを検索します	自動
list_favorite_card_suites	お気に入り登録（ハートを付けた）招待状デザインのスイートを一覧表示します	自動
get_rsvp_page	ウェディングサイトのRSVPページ設定（タイトル、紹介文、表示設定、カスタマイズ）を取得します	自動
create_card_project	デザインスイートとメインのバリエーション（特定のサイズ／用紙）を指定して、新しい招待状プロジェクトを作成します	ホストのプロンプト
swap_card_project_variation	プロジェクトの1つ以上のカスタマイズを、別のバリエーション（用紙の種類、色、サイズ）に切り替えます	ホストのプロンプト
set_card_project_guests	招待状プロジェクトのゲストグループを有効／無効にし、印刷する氏名と住所のフォントサイズを任意で上書き設定します	ホストのプロンプト
preview_card_template	テキストを差し込んだ招待状テンプレートのプレビューを生成します	自動
preview_qrcode	招待状用のQRコードPNGを生成します	自動
set_card_project_qrcode	招待状プロジェクトの指定ページにQRコードを配置（または更新）します	ホストのプロンプト

検出と健全性チェック

ツール	機能	権限
zola_healthcheck	認証情報とZolaへの接続を確認し、どの段階で失敗したかを示します	自動
get_wedding_dashboard	プランニングダッシュボードの概要を取得します	自動
search_storefronts	カテゴリ／場所でマーケットプレイスを検索します	自動
get_storefront	ベンダーのストアフロントの詳細を取得します	自動
list_favorites	お気に入り登録したベンダーを一覧表示します	自動

トラブルシューティング

「Zola auth: set ZOLA_REFRESH_TOKEN, or install the ContextMint Bridge extension…」 — 設定ファイルにZOLA_REFRESH_TOKENを設定するか、ContextMint Bridge拡張機能をインストールしてzola.comにサインインしてください。

「Zola session refresh failed」 — リフレッシュトークンの有効期限が切れている（約1年）か、取り消されています。新しいusr Cookie（DevTools）を取得するか、ContextMint Bridge拡張機能をインストールした状態でzola.comに再度サインインしてください。

モバイルAPIからの403 — x-zola-session-idヘッダーが欠落している可能性があります。最新バージョンに更新してください。

Claudeにツールが表示されない — Claude Desktop → Settings → Developerに移動して、接続済みのサーバーを確認してください。設定を編集した後は、アプリを完全に終了してから再起動してください。

セキュリティ

• リフレッシュトークンは、ローカルの.envまたは設定ファイル（設定した場合）、あるいはユーザーのブラウザーのCookieストア（fetchproxy経由）にのみ保存されます
• 環境変数として渡され、ログに記録されることはありません
• サーバーはiOSアプリと同じフローでZolaのモバイルAPIに認証します
• アカウントIDとレジストリIDはAPIから自動的に解決されます（手動設定は不要です）

開発

npm test        # run the test suite (vitest)
npm run build   # compile TypeScript → dist/

プロジェクト構成

src/
  client.ts               Zola mobile API client (auth, token refresh, context)
  index.ts                MCP server entry point
  tools/
    index.ts              TOOL_REGISTRARS — every tool module the server registers
    vendors.ts            list, search, add, update, remove vendors
    budget.ts             get budget, update budget items
    guests.ts             list, add, update, remove guests
    seating.ts            seating charts, seat assignment
    inquiries.ts          vendor inquiry conversations
    events.ts             events, RSVPs, gift tracker, registry
    event-invitations.ts  which guests are invited to which events
    registry-items.ts     registry item add / update / remove
    reconcile-registry.ts registry vs gift-tracker reconciliation
    website.ts            website pages and wedding settings
    website-content.ts    FAQs, home sections, things to do, travel
    website-theme.ts      website theme and customizations
    invitations.ts        invitation / save-the-date card projects
    discover.ts           dashboard, storefront search, favorites
    healthcheck.ts        zola_healthcheck
tests/                    one *.test.ts per module, plus manifest/docs/annotation sync tests

認証フロー

すべてのツールは、Bearer JWT認証を使用してZolaモバイルAPI（mobile-api.zola.com）にアクセスします。

1. リフレッシュトークンJWTを使ってPOST /v3/sessions/refreshを実行し、30分間有効なセッショントークンを取得します
2. すべてのAPI呼び出しで、Authorization: Bearer <session_token>とx-zola-session-idヘッダーを使用します
3. 401が返された場合、自動的にトークンを更新し、1回再試行します
4. セッショントークンは有効期間中（30分）キャッシュされます

MCPB バンドルのビルド

.mcpb バンドルは、バージョンタグがプッシュされるとリリースワークフローによって自動的にビルドされます。ローカルでビルドするには、次のコマンドを実行します。

npm run build
npx @anthropic-ai/mcpb pack

これにより、manifest.json の設定を使用して zola-mcp.mcpb が生成されます。バンドルには、コンパイル済みの dist/bundle.js と、ZOLA_REFRESH_TOKEN 用のユーザー設定プロンプトが含まれます。

リリース

リリースは GitHub Actions によって自動化されています。

1. Cut & Bump ワークフローを実行します（手動で起動）。現在のバージョンにタグを付け、パッチバージョンを上げます。
2. タグのプッシュをきっかけに Release ワークフローが実行され、次の処理を行います。
   • CI を実行します（ビルドとテスト）。
   • .skill および .mcpb バンドルをパッケージ化します。
   • npm に公開します。
   • バンドルを含む GitHub Release を作成します。

ライセンス

MIT