# Luma (eventos) — how to use (mcp.ai)

Manage your Luma (lu.ma) events straight from your AI agent: create and edit events, set the venue and its map pin, publish free or paid ticket types, issue discount coupons, register and invite people, approve or decline sign-ups, add hosts, and read the guest list and the calendar's contacts. To pick a venue, a lookup tool turns a plain-text address into map coordinates. Connect with your own API key from Settings → Developer on the calendar (requires the Luma Plus plan). It does not search other people's public events: the key only sees the calendar it manages. Not an official Luma service. Not to be confused with Luma AI (Dream Machine), a different company.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_luma?ms=1788915120000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `luma_add_guests`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/luma`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/luma/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/luma/add/guests` — Registers people directly on an event, skipping the public registration form. Each guest needs an email and may have a name. They are added as 'approved' (going) by default, and Luma emails them unles
  - body: { event_id: string, guests: object[], approval_status?: string, event_ticket_type_id?: string, send_email?: boolean, account?: string, event_ids?: string[], event_ticket_type_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/add/host` — Adds a co-host to an event by email. access_level 'manager' (the default) can edit the event, 'check-in' can only check guests in, and 'none' is a credit-only host. is_visible controls whether they ap
  - body: { event_id: string, email: string, name?: string, access_level?: string, is_visible?: boolean, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/cancel/event` — Cancels an event. Called WITHOUT confirm it only previews the impact (how many approved guests, whether there are paid guests) and cancels nothing. Show that preview to the user and only call again wi
  - body: { event_id: string, confirm?: boolean, should_refund?: boolean, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/create/coupon` — Creates a discount coupon on an event. The discount is either a percentage (percent_off, 1 to 100) or a fixed amount (cents_off plus currency, where 1000 means R$10.00) - send one, not both. remaining
  - body: { event_id: string, code: string, percent_off?: number, cents_off?: integer, currency?: string, remaining_count?: integer, event_ticket_type_id?: string, valid_start_at?: string, valid_end_at?: string, account?: string, event_ids?: string[], event_ticket_type_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/create/event` — Creates an event on the connected calendar and returns its id and public URL. Name, start_at and timezone are required; timezone must be an IANA name such as America/Sao_Paulo. To set the venue, first
  - body: { name: string, start_at: string, end_at?: string, timezone: string, description_md?: string, visibility?: string, slug?: string, cover_url?: string, max_capacity?: integer, waitlist_status?: string, registration_open?: boolean, show_guest_list?: boolean, location_address?: string, latitude?: number, longitude?: number, google_place_id?: string, meeting_url?: string, location_visibility?: string, account?: string, google_place_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/create/ticket/type` — Creates a ticket type on an event. type 'free' needs nothing else; type 'paid' needs cents (the price in the smallest currency unit, so 5000 means R$50.00) and a three-letter currency such as brl or u
  - body: { event_id: string, name: string, type: string, cents?: integer, currency?: string, description?: string, max_capacity?: integer, require_approval?: boolean, is_hidden?: boolean, valid_start_at?: string, valid_end_at?: string, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/find/place` — Turns a place written in plain text into real venue candidates, each with a formatted address and its latitude and longitude. This is the step to run BEFORE creating or updating an event with a physic
  - body: { query: string, country_code?: string, limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/luma/get/calendar` — Returns the calendar this API key manages: name, description, public URL, timezone, geo settings and social links. A Luma API key is scoped to one calendar, so this is the workspace every other tool o
  - body: { account?: string }
- `POST https://api.mcp.ai/api/luma/get/event` — Opens one event by id and returns the full record: name, description, start and end, timezone, address and coordinates, visibility, capacity, waitlist, cover, ticket setup and the hosts.
  - body: { event_id: string, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/get/guest` — Returns one guest of an event. The identifier can be the guest id (gst-), a ticket key, a guest key (g-) or the person's email address, which makes it the way to look someone up by email.
  - body: { event_id: string, id: string, account?: string, event_ids?: string[], ids?: string[] }
- `POST https://api.mcp.ai/api/luma/list/accounts` — Lists the Luma calendars connected to this install (id, label and nickname). A Luma API key is scoped to one calendar, so each connection is one calendar. Use the returned id or label as the account a
  - body: { account?: string }
- `POST https://api.mcp.ai/api/luma/list/contacts` — Lists the contacts of the connected calendar: everyone who has ever registered for one of its events, with name, email, how many events they attended and revenue. Search by name or email with query an
  - body: { query?: string, tags?: string[], sort_column?: string, sort_direction?: string, pagination_cursor?: string, pagination_limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/luma/list/coupons` — Lists the discount coupons of an event with code, discount, remaining uses and validity window.
  - body: { event_id: string, pagination_cursor?: string, pagination_limit?: integer, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/list/events` — Lists the events on the connected calendar, newest first by start date, with id, name, start and end time, timezone, location, cover and URL. Filter a window with after and before (ISO 8601 datetimes)
  - body: { after?: string, before?: string, status?: string, access?: string[], sort_direction?: string, pagination_cursor?: string, pagination_limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/luma/list/guests` — Lists the guests of an event with name, email, approval status, ticket, registration answers and check-in time. Filter with approval_status ('approved', 'pending_approval', 'invited', 'declined', 'wai
  - body: { event_id: string, approval_status?: string, sort_column?: string, sort_direction?: string, pagination_cursor?: string, pagination_limit?: integer, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/list/ticket/types` — Lists the ticket types of an event with id, name, price, currency, capacity and sale window. Run this before adding guests with a specific ticket or before creating a coupon restricted to one ticket t
  - body: { event_id: string, include_hidden?: boolean, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/lookup/event` — Finds an event from its public Luma URL (e.g. https://luma.com/aloha) and returns its id and details. Use this when the user pastes a link instead of an id.
  - body: { url?: string, event_id?: string, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/send/invites` — Sends Luma invitations by email to a list of people. Unlike luma_add_guests this does not register them: they receive an invite and choose to accept. The optional message is limited to 200 characters.
  - body: { event_id: string, guests: object[], message?: string, account?: string, event_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/update/event` — Updates an existing event. Only the fields you send change; everything else is left as is. To set the venue, first call luma_find_place with the place in plain text (e.g. 'Pinheiros, Sao Paulo' or 'Mo
  - body: { event_id: string, name?: string, start_at?: string, end_at?: string, timezone?: string, description_md?: string, visibility?: string, slug?: string, cover_url?: string, max_capacity?: integer, waitlist_status?: string, registration_open?: boolean, show_guest_list?: boolean, location_address?: string, latitude?: number, longitude?: number, google_place_id?: string, meeting_url?: string, location_visibility?: string, suppress_notifications?: boolean, account?: string, event_ids?: string[], google_place_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/update/guest/status` — Approves, declines, waitlists or sends a guest back to pending. The guest can be identified by guest id (gst-), ticket key, guest key (g-) or email. Moving a paying guest out of 'approved' requires de
  - body: { event_id: string, guest_id: string, status: string, should_refund?: boolean, send_email?: boolean, message?: string, account?: string, event_ids?: string[], guest_ids?: string[] }
- `POST https://api.mcp.ai/api/luma/whoami` — Returns the Luma user the API key belongs to (name, email, avatar). Use it to confirm the connection works and which account is being managed.
  - body: { account?: string }

## Example prompts
- "Create a meetup on Oct 15 at 7pm at Cubo Itau in Sao Paulo and send me the link"
- "How many people are confirmed for the next event? List who is still pending approval"
- "Add an Early bird ticket at R$50 with 30 seats and a COMMUNITY coupon for 20% off"

## More
- Page: https://mcp.ai/luma
- Agent spec (llms.txt): https://mcp.ai/luma/llms.txt
- Postman collection: https://mcp.ai/luma/postman.json