invitaai-mcp

MCP server for InvitaAI, a digital invitations platform. Create events, invitations and personalized guest links, and follow RSVPs from a phone, Claude Code, or any MCP client.

"Create a wedding invitation for Dec 12 at Hacienda Los Arcos, champagne theme, and add my aunt Rosa with 2 seats."

Two ways to run the same tools

Both paths end with the same 90-day inv_ token and the same tools. The server holds no database credentials either way: it acts as the user through the same public API as the web app, so ownership checks and business rules stay server-side.

Remote: connecting from a phone

sequenceDiagram
    participant U as User (phone)
    participant C as AI app (Claude, ChatGPT…)
    participant S as invitaai.com/mcp + OAuth
    U->>C: adds the connector URL
    C->>S: POST /register (dynamic client registration)
    C->>U: opens /authorize -> consent screen
    U->>S: logs in, clicks Authorize
    S-->>C: authorization code
    C->>S: POST /token (code + PKCE verifier)
    S-->>C: token (90 days)
    C->>S: MCP calls with Authorization: Bearer inv_...

Local: connecting a CLI on your own machine

sequenceDiagram
    participant U as User
    participant A as AI client + invitaai-mcp (stdio)
    participant API as invitaai.com API
    A->>API: POST /api/device/code
    API-->>A: user_code + link
    A->>U: "Open the link and confirm BCDF-GHJK"
    U->>API: logs in, clicks Approve
    A->>API: POST /api/device/token (polling)
    API-->>A: token (90 days), stored locally
    A->>API: Authorization: Bearer inv_...

Related MCP server: Google-Calendar Universal MCP

Security model

Tools

Prompt: guided_invitation walks the user through event data, theme, photos, texts and guests one question at a time (a slash command in clients that support prompts).

Design notes

• Edits merge, never replace. The API stores invitation texts and design as whole objects, so every edit tool reads the current one and writes back only the requested change. Changing the music can't wipe the gallery.

• Creating a second invitation for an event is refused, pointing the model at update_invitation. Without that, an agent asked to "change the colour" creates a duplicate and the shared link goes stale.

• The client model writes the invitation texts. The platform's templates fill the rest, so no section is ever left blank and no extra LLM bill is added.

• Everything the platform already measures is reachable. Views, seats allowed vs. confirmed, who answered and when, contact details, response rate and per-event totals were all being collected and only half-exposed; an agent that can't see them can't help the host follow up.

• No option lists live in this repo. Event types and themes used to be duplicated here and drifted from the platform; every value is now validated against the served catalog, and a wrong one comes back with the real options.

• The agent designs, within a catalog. get_design_options returns the themes, textures, ornaments, fonts, layouts and cover styles the platform actually renders — served by the app, so the agent can't drift from what exists — and customize_design applies a chosen combination plus a custom palette. Free-form CSS is deliberately not exposed: an invitation shown to guests shouldn't depend on a model writing stylesheets.

• Addresses are geocoded, and failures are reported. A map button built from raw text opens an empty search; the API resolves the address first and the tool tells the agent when it couldn't, so it asks the user instead of leaving a dead button in front of the guests.

• Song links are verified, not trusted. Models invent plausible YouTube/Spotify URLs, so set_music resolves the link through the provider's oEmbed endpoint: a fake link is refused and a real one supplies the actual track title. Spotify answers come with a note that guests without a session only hear a 30-second preview.

• The agent is blind to the result. Its instructions say so: propose named looks, apply, and ask the user to open the link and react. The loop is human-in-the-eye, not guesswork.

• Only public https image links reach the invitation (javascript:, http: and non-images are rejected).

• The user's own photos travel by link, not through the model. Tools can't receive files, so create_photo_upload_link returns a short-lived, single-invitation upload link the user opens on their phone. Errors about image URLs point the model at that tool instead of dead-ending.

Use it

Remote (phone or desktop, nothing to install): add https://invitaai.com/mcp as a custom connector in your AI app — no client ID or secret, the server registers the app itself — and approve the consent screen. Instructions per app live at invitaai.com/agentes.

Local (stdio):

git clone https://github.com/David-Solano/invitaai-mcp && cd invitaai-mcp
python -m venv .venv && .venv/bin/pip install -e .     # Windows: .venv\Scripts\pip
claude mcp add invitaai -- /absolute/path/to/.venv/bin/invitaai-mcp

Then ask your agent: "conéctame a InvitaAI". INVITAAI_URL points it at another deployment (e.g. local dev).

The deployment mounts this package with build_server(client, with_local_login=False), which drops the two device-login tools (OAuth already authenticated the user) and takes the token from the request instead of a file.

Development

pip install -e ".[dev]"
pytest

Tests drive the server through the MCP protocol (in-memory client) against a fake of the InvitaAI API.

Tool names, arguments and results are in English; the strings a person reads (errors, notes the assistant relays) stay in Spanish, the product's language.

Built with Claude Code as a pair programmer; design decisions and review by the author.

MIT