better_luma
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@better_luma find events in San Francisco this weekend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Better Luma FastMCP
A read-only FastMCP server for the existing Better Luma / WAP events backend. It gives MCP clients such as Codex structured tools for discovering Luma, Posh, and Partiful events.
This public repository contains the MCP adapter only. It contains no session keys, browser cookies, or private backend code.
How it works
Codex or another MCP client
|
| MCP over local stdio
v
Better Luma FastMCP (this repository)
|
| HTTP + optional private auth headers
v
WAP FastAPI backend at 127.0.0.1:8000
|
+---- Luma / Posh / PartifulFastMCP defines the tool schemas and handles the MCP protocol. This adapter validates each tool call, maps it to a read-only HTTP request, and returns the backend's JSON. The existing WAP backend remains responsible for platform integrations and scraping.
Related MCP server: partiful-mcp
Tools
Tool | Purpose |
| Check backend availability |
| List cities supported by a platform |
| List event category filters |
| Browse platform events by city |
| Fetch one event by ID or Luma slug |
| Search one platform |
| Fetch a permitted guest list |
| Collect events and visible attendees without auto-RSVP |
| Read the authenticated user's managed, upcoming, or past events |
| Verify whether the authenticated user hosts an event |
Every MCP tool is annotated read-only. OTP, token-pool, token-revocation, and RSVP routes are deliberately not exposed. Partiful scrape requests always set auto_rsvp=false.
Folder separation
Folder | Role |
| Public FastMCP adapter |
| Existing Better Luma frontend |
| Existing private FastAPI backend |
Keeping the adapter separate makes it safe to publish and lets the web app and MCP reuse the same backend logic.
Install and run
Requirements: Python 3.12+, uv, and the existing WAP backend.
Install the MCP environment:
cd /Users/samsavage/Documents/luma-mcp
uv sync --lockedStart the WAP backend in a separate terminal:
cd /Users/samsavage/wap
source venv/bin/activate
uvicorn src.luma.api.main:app --host 127.0.0.1 --port 8000Run the MCP server over stdio:
cd /Users/samsavage/Documents/luma-mcp
uv run better-luma-mcpAn MCP client owns that process's stdin and stdout, so do not type into it directly.
Configure Codex
Set any private tokens in the environment that launches Codex, then add this to ~/.codex/config.toml:
[mcp_servers.better_luma]
command = "/Users/samsavage/Documents/luma-mcp/.venv/bin/better-luma-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 200
env_vars = ["LUMA_AUTH_SESSION_KEY", "POSH_JWT_TOKEN", "PARTIFUL_AUTH_TOKEN"]
[mcp_servers.better_luma.env]
BETTER_LUMA_API_BASE_URL = "http://127.0.0.1:8000"env_vars forwards only those named variables from the local environment into the MCP child process. The command, environment, and timeout fields follow the official Codex stdio MCP configuration. Restart Codex after changing its configuration.
Public discovery tools work without credentials.
Luma authentication
The agent does not receive or request your Luma session key as a tool argument. The boundary is:
You sign in to Luma in your browser.
In browser developer tools, open Application (or Storage) > Cookies and select the Luma origin (
luma.comorlu.ma).Copy the value of the cookie named
luma.auth-session-key.Export it as
LUMA_AUTH_SESSION_KEYin the environment that launches Codex.Restart Codex so it can forward the named variable to the MCP process.
The MCP process reads the variable and sends it to the local WAP backend in the private x-auth-token header. It is never included in the MCP tool schema or normal tool results, so the model does not need to see it.
Do not paste a session key into a prompt, commit it, or put it into this repository. Treat it like a password and rotate it by signing out of Luma if it is exposed. BETTER_LUMA_AUTH_TOKEN is accepted as a backwards-compatible alias.
Configuration
Variable | Default | Description |
|
| WAP FastAPI base URL |
|
| Normal backend request timeout |
|
| Long scrape request timeout |
| unset | Optional Luma session key for private reads |
| unset | Optional Posh JWT |
| unset | Optional Partiful bearer token |
Develop and test
uv sync --locked
uv run pytest -q
uv buildThe tests use in-memory FastMCP clients and mocked HTTP transports; they do not require real credentials or contact event platforms.
License
MIT
Available Tools
10 toolsget_eventGet EventBRead-onlyIdempotent
Get details for one event ID or Luma URL slug.
Inputs: event_id (required), platform.
get_event_guestsGet Event GuestsBRead-onlyIdempotent
Get an event guest list when the platform permits access.
Inputs: event_id (required), limit, platform, ticket_key.
healthHealthARead-onlyIdempotent
Check whether the Better Luma/WAP backend is available.
Inputs: no named parameters.
list_citiesList CitiesARead-onlyIdempotent
List cities supported by an event platform.
Inputs: platform.
list_eventsList EventsBRead-onlyIdempotent
List events from Luma, Posh, or Partiful.
Inputs: city, limit, offset, search, +3 more.
list_event_typesList Event TypesARead-onlyIdempotent
List the backend's event category filters for one platform.
Inputs: platform.
list_my_luma_eventsList My Luma EventsARead-onlyIdempotent
List the authenticated user's managed, upcoming, or past Luma events.
Inputs: limit, timeframe.
scrape_cityScrape CityBRead-onlyIdempotent
Collect events and visible attendees without automatically RSVPing.
Inputs: city, limit, offset, platform, +3 more.
search_eventsSearch EventsARead-onlyIdempotent
Search event names and descriptions on one platform.
Inputs: query (required), city, limit, platform, +1 more.
verify_luma_hostVerify Luma HostARead-onlyIdempotent
Check whether the authenticated Luma user hosts an event.
Inputs: event_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target distinct actions, but some overlap exists: list_events and scrape_city both collect events, get_event_guests and scrape_city both collect attendees, and list_my_luma_events overlaps with verify_luma_host in checking host status. The descriptions reduce ambiguity but the boundaries are not always crisp.
The naming pattern is mostly consistent verb_noun snake_case, e.g. list_events, get_event, search_events, verify_luma_host. The lone 'health' tool breaks the pattern by not using a verb, though it is still understandable.
Ten tools is a well-scoped count for an event aggregation/read-only API. Each tool covers a distinct aspect of the domain without unnecessary bloat or obvious redundancy.
The toolset covers the core read-only workflow: event types, cities, event listing/search/detail, guests, city scraping, and authenticated user event queries. Minor gaps exist such as no explicit platform-list tool or direct attendee export beyond guests, but agents can mostly accomplish the intended tasks.
Maintenance
Related MCP Connectors
Read-only search of upcoming local events worldwide: music, comedy, AI/tech, arts, food, sports.
Read your events, sales, orders and attendees from your AI assistant. OAuth sign-in, read only.
Find every upcoming event on Lu.ma by city, calendar or category, by Magnova
Related MCP Servers
- AlicenseAqualityDmaintenanceDiscovers events from Luma's public feed and subscribed calendars, with distance filtering, category search, and ICS export. No API key required for basic discovery.421 PyPIMIT
- AlicenseAqualityBmaintenanceEnables AI agents to view Partiful events, RSVPs, hosted events, mutual connections, and user profiles via a community-built MCP server.419 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search upcoming public events and group topic categories by keyword, city, or group slug, and to retrieve full details for individual events and groups, keylessly and without touching attendee or member data.84 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to browse public event listings from explore pages and fetch full detail for a single event — titles, descriptions, times, locations, host display names, and aggregate RSVP counts — across eight supported city regions. Keyless and read-only, with no guest lists, contact info, or authentication required.85 npmMIT