Luma Events MCP Server

An open-source Model Context Protocol (MCP) server for managing Luma events from MCP-compatible AI clients.

The server connects to the calendar associated with your Luma API key. It can list and inspect events, create or update events after explicit confirmation, inspect guest registrations, and return privacy-conscious registration summaries.

Features

• Verify the configured Luma API connection.
• List approved or pending calendar events.
• Retrieve complete details for an event.
• Create events after explicit user confirmation.
• Update event details and registration settings after explicit confirmation.
• List guests for event operations.
• Count registration states and check-ins without returning guest identities.
• Paginate automatically when producing registration summaries.

Write operations are guarded by a required confirmed value. MCP clients should show the proposed event details to the user and obtain explicit approval before calling a write tool.

Screenshots

Discover available capabilities

List upcoming events

Analyze guest attendance

Guest identities have been redacted from this public example.

Available tools

verify_connection

Checks the API key and returns the authenticated Luma user.

list_events

Lists calendar events. Supports date ranges, approval status, pagination limits, and pagination cursors.

get_event

Returns complete details for a single event.

create_event

Creates an event after explicit confirmation. Supports event names, dates, timezones, descriptions, capacity, online meeting URLs, physical locations, visibility, registration, waitlist, and guest-list settings.

update_event

Updates selected event fields after explicit confirmation.

list_guests

Lists event guests, optionally filtered by approval status. This tool may return personal information and should only be used for legitimate event operations.

registration_summary

Returns totals by registration state and the number of checked-in guests without exposing names or email addresses.

Requirements

• Node.js 20 or newer
• pnpm
• A Luma calendar with API access
• A Luma API key
• An MCP-compatible client such as Cursor or Codex

Getting a Luma API key

Generate a calendar API key by following the Luma API documentation. The key determines which calendar the server can access.

Treat the key as a secret. Never commit it, include it in screenshots, or place it directly in a tracked MCP configuration file.

Installation

Clone the repository and enter this plugin directory:

git clone https://github.com/Blackie360/luma-events-mcp.git
cd luma-events-mcp

Install dependencies and build the server:

corepack enable
pnpm install
pnpm build

The production entry point is generated at dist/index.js.

Configuration

The server requires the following environment variable:

export LUMA_API_KEY="your-luma-api-key"

An optional API base URL can be supplied for testing or compatible proxies:

export LUMA_API_BASE="https://public-api.luma.com"

The server does not load .env files automatically. For local development, you can create an ignored .env file and load it into your shell before running the server:

set -a
source .env
set +a

Example .env:

LUMA_API_KEY=your-luma-api-key

Running locally

Build and start the stdio MCP server:

pnpm build
pnpm start

The process communicates over standard input and output, so it normally appears idle when started directly. An MCP client is expected to launch and communicate with it.

Connecting an MCP client

Configure your client to run the built server with Node.js. Use absolute paths unless the client supports a working-directory option.

{
  "mcpServers": {
    "luma-events": {
      "command": "node",
      "args": ["/absolute/path/to/plugins/luma-events/dist/index.js"]
    }
  }
}

Make LUMA_API_KEY available to the environment that launches your MCP client, or use the client's secure secret/environment-variable configuration. Restart the client after updating its environment or MCP configuration.

This repository also includes:

• .mcp.json for clients that support plugin-provided MCP configuration.
• .codex-plugin/plugin.json with Codex plugin metadata.

After connecting, ask the client to run verify_connection before using the other tools.

Example prompts

• "Verify my Luma connection."
• "Show my upcoming Luma events."
• "Show the details for the next event."
• "Summarize registrations for my next event."
• "Prepare an event for Friday at 5 PM, but do not create it until I confirm."
• "Close registration for this event after showing me the proposed change."

Development

Run the TypeScript compiler checks:

pnpm check

Build the project:

pnpm build

Run the test suite:

pnpm test

The test suite covers write confirmation, API error reporting, registration pagination, and privacy-conscious summaries.

Project structure

.
├── .codex-plugin/plugin.json  # Codex plugin metadata
├── .mcp.json                  # Plugin MCP server configuration
├── src/index.ts               # MCP server and Luma API integration
├── src/index.test.ts          # Node.js tests
├── package.json               # Scripts and dependencies
└── tsconfig.json              # TypeScript configuration

Security and privacy

• Never commit LUMA_API_KEY or any .env file.
• Review requested changes before confirming write operations.
• Use list_guests only when guest-level data is necessary.
• Prefer registration_summary when only aggregate counts are required.
• Keep dependencies updated and report vulnerabilities privately to the maintainers.

Contributing

Contributions are welcome:

1. Fork the repository.
2. Create a focused branch.
3. Add or update tests for your change.
4. Run pnpm check and pnpm test.
5. Open a pull request explaining the change and its motivation.

Please avoid including API keys, guest information, or other private event data in issues, tests, commits, or pull requests.

API

The server uses Luma's official API at https://public-api.luma.com. API keys are scoped to the calendar and permissions configured in Luma.

License

This project is available under the MIT License.