Zola Mcp

Zola MCP

[CI] [npm] [license]

A Model Context Protocol server that connects Claude to Zola, giving you natural-language access to your wedding vendors, budget, guest list, seating chart, events, registry, inquiries, and more.

[!WARNING] AI-developed project. This codebase was entirely built and is actively maintained by Claude Code. No human has audited the implementation. Review all code and tool permissions before use.

What you can do

Ask Claude things like:

• "How's wedding planning going?"
• "Find a photographer in Charlotte, NC"
• "Update the venue cost to $25,000"
• "Who hasn't RSVP'd yet?"
• "Seat Pat at Table 1"
• "Any new vendor messages?"
• "Add my cousin Mike to the guest list"
• "Show me the gift tracker"

Requirements

• Claude Desktop or Claude Code
• Node.js 22 or later
• A Zola account
• For the no-env-var path: the ContextMint Bridge Chrome extension (Safari is not available yet — use Chrome for now)

Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

1. This server accesses your own Zola account. Auth happens via your own credentials. It does not — and cannot — access anyone else's wedding website, registry, or guest list.

2. Zola's Terms of Use govern your use of this server, just as they govern your direct use of zola.com. The clauses most relevant here:

[You may not use] any hardware or software intended to surreptitiously intercept or otherwise obtain any information… including but not limited to the use of any "scraping" or other data mining techniques, robots or similar data gathering and extraction tools.

And, critically, on agent-acting-as-you: "You are responsible for maintaining the confidentiality of your account and password… You accept full responsibility for all activities that occur under your account and password, even if such actions are undertaken by your Authorized Agent or other third party."

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Zola's ToU is explicit: this MCP acting as your Authorized Agent counts as you.

3. Personal, non-commercial use only. This project is not affiliated with, endorsed by, sponsored by, or in partnership with Zola, Inc. It is a personal automation tool for one couple to manage their own wedding website, registry, vendor research, and guest list. Do not use it to bulk-extract Zola's vendor directory, scrape registries, or compete with Zola.

4. Stability is not guaranteed. This server may call internal Zola endpoints that change without notice. It may break.

5. You accept full responsibility for any consequences of using this server in connection with your Zola account — rate limiting, account warnings, suspension, or any enforcement action. Per Zola's ToU, anything this MCP does under your account is your action — review guest list edits, registry changes, and inquiries before confirming. If Zola objects to your use, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Zola's actual ToU.

Installation

Option A — MCPB (recommended)

Download the latest .mcpb bundle from Releases and install:

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

You'll be prompted for your ZOLA_REFRESH_TOKEN (see Getting your refresh token below).

Option B — npm

npx -y zola-mcp

Add to your Claude config (.mcp.json or Claude Desktop config):

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

Option C — from source

git clone https://github.com/chrischall/zola-mcp.gitcd zola-mcpnpm installnpm run build

Add to Claude Desktop config:

• 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"      }    }  }}

Getting your refresh token

You have two options. Both produce the same usr cookie value — a ~1-year JWT that doubles as the refresh token.

Option A — ContextMint Bridge (recommended)

1. Install ContextMint Bridge — Chrome: download the chrome zip from the latest release, unzip it, and load it unpacked at chrome://extensions (Developer mode on). Safari is not available yet (it will ship inside the ContextMint app, which has no public download), so use Chrome for now.

   ContextMint Bridge is the fetchproxy browser extension under its new name, from the same maintainer — fetchproxy's own README (fetchproxy#extension) points to it. Its source is public at nullnet-app/contextmint-bridge: build it yourself, or check a release zip against the .sha256 file published beside it (shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256).

2. Sign in at zola.com/account/login in that browser.

3. Leave ZOLA_REFRESH_TOKEN unset in your Claude config.

On the first tool call, the MCP asks the extension for the HttpOnly usr cookie via chrome.cookies.get, then operates direct-to-API from Node — the bridge is never in the hot path.

That cookie is the ~1-year refresh token, so it is cached at $MCP_DATA_DIR/.zola-mcp/refresh-token.json (falling back to $HOME, mode 0600). Later starts read it from there and need no browser at all, which is what makes the server usable on a remote host where none exists. If the API ever rejects the cached token — you signed out, or it aged past its year — it is discarded automatically and the extension is asked again. To re-auth, just sign back in to zola.com. Set ZOLA_TOKEN_CACHE=false to keep nothing on disk and ask the browser every time.

You can opt out of this fallback with ZOLA_DISABLE_FETCHPROXY=1 (e.g. in headless / CI environments where no extension is available).

Option B — manual (DevTools)

1. Sign in at zola.com/account/login in any browser.
2. Open DevTools → Application → Cookies → https://www.zola.com.
3. Copy the value of the usr cookie.
4. Paste it into .env as ZOLA_REFRESH_TOKEN=<value> (or into your Claude config env block).

Restart Claude Desktop

Quit completely (Cmd+Q on Mac) and relaunch.

Verify

Ask Claude: "How's wedding planning going?" — it should show your wedding dashboard.

Credentials

Available tools

77 tools across 12 areas. The Permission column says what stands between a call and a change:

• Auto — read-only; runs without asking.
• Host prompt — a write. Clients that prompt before non-read-only tools (Claude Code, Claude Desktop) ask you first; the server itself does not, so on a client with no prompt (claude.ai) it runs on the first call.
• Server gate — a write that cannot be undone or that changes what guests see, so the server confirms it itself on every client.

The server-gated writes are remove_guest, update_event, update_wedding_settings, remove_faq, remove_home_section, remove_poi, remove_travel_item, remove_registry_item, set_event_guests and remove_event_invitation (set_event_guests only when it uninvites anyone). Each first shows a preview naming the household, event, item or page content and exactly what changes (for a slug change, the old and new website URL; a registry item on a private or passcode-gated registry, or outside the default collection, is shown by id because only the public page names it), then proceeds only once you approve — see MCP_CONFIRM_MODE above.

Vendors

Budget

Guests

Seating

Inquiries

Events & RSVPs

Registry & Gifts

Wedding website — pages & settings

Wedding website — content (FAQs, home, things to do, travel)

Wedding website — theme

Invitations & save-the-dates

Discovery & health

Upgrading

next release

preview_qrcode now hands the image back through the shared delivery ladder. A normal QR preview is unchanged: one image content block, PNG. What changed are the edge cases:

• An image type is always a bare media type (image/png, never image/png;charset=UTF-8), which a host's image renderer would reject.
• A non-image type that Zola might return comes back as an embedded resource block locally (it was mislabelled as an image block), and as a download link on a hosted install.
• An image over 10 MiB is never inlined. On a hosted install it comes back as one text block of JSON, { via: "link", fileName, mimeType, sizeBytes, url, expiresAt, note }, where url is a signed link that expires at expiresAt. With no blob store the tool fails with a too_large error.

Troubleshooting

"Zola auth: set ZOLA_REFRESH_TOKEN, or install the ContextMint Bridge extension…" — either set ZOLA_REFRESH_TOKEN in your config or install the ContextMint Bridge extension and sign into zola.com.

"Zola session refresh failed" — your refresh token has expired (~1 year) or been revoked. Either capture a new usr cookie (DevTools) or sign back into zola.com with the ContextMint Bridge extension installed.

403 from mobile API — the x-zola-session-id header may be missing. Update to the latest version.

Tools not appearing in Claude — go to Claude Desktop → Settings → Developer to see connected servers. Make sure you fully quit and relaunched after editing the config.

Security

• The refresh token lives only in your local .env or config file (when set) or in the user's browser cookie store (fetchproxy path)
• It is passed as an environment variable and never logged
• The server authenticates with Zola's mobile API using the same flow as the iOS app
• Account and registry IDs are auto-resolved from the API (no manual configuration needed)

Development

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

Project structure

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_healthchecktests/                    one *.test.ts per module, plus manifest/docs/annotation sync tests

Auth flow

All tools use the Zola mobile API (mobile-api.zola.com) with Bearer JWT auth:

1. POST /v3/sessions/refresh with refresh token JWT → returns 30-min session token
2. All API calls use Authorization: Bearer <session_token> + x-zola-session-id header
3. On 401, auto-refreshes and retries once
4. Session tokens are cached for their lifetime (30 min)

Building the MCPB bundle

The .mcpb bundle is built automatically by the Release workflow when a version tag is pushed. To build locally:

npm run buildnpx @anthropic-ai/mcpb pack

This produces zola-mcp.mcpb using the configuration in manifest.json. The bundle includes the compiled dist/bundle.js and user config prompts for ZOLA_REFRESH_TOKEN.

Releasing

Releases are automated via GitHub Actions:

1. Run the Cut & Bump workflow (manual trigger) — tags the current version and bumps patch
2. The tag push triggers the Release workflow which:
   • Runs CI (build + test)
   • Packages .skill and .mcpb bundles
   • Publishes to npm
   • Creates a GitHub Release with the bundles

License

MIT