Luma MCP Server (`luma-mcp`)

A Model Context Protocol (MCP) server for searching, discovering, and extracting upcoming Luma (lu.ma) events, tech talks, AI meetups, and hackathons with citation-ready line numbering.

Designed for seamless integration with LLM applications such as Claude Desktop, Cursor, and custom autonomous agents.

Features

Dual-Mode Retrieval:
- Keyword Search Mode: Fast, lightweight keyword matching over title, tags, hosts, and descriptions.
- Live API Pagination Mode: Direct real-time pagination from Luma's discover API.
Citation-Ready Line Numbering: All event content is formatted into Markdown with line numbers ( 1|..., 2|...), allowing LLMs to provide exact line citations.
ProseMirror-to-Markdown Engine: Parses rich text descriptions, links, bullet lists, and agendas from Luma into clean GitHub-flavored Markdown.
Multi-Location & Category Filtering: Built-in support for tech hubs including San Francisco, Berkeley, New York, Palo Alto, San Jose, and Shanghai, alongside category filters (ai, crypto, tech).
Date Range Constraints: Filter events with strict date constraints (MM:DD:YY or YYYY-MM-DD).
Zero Heavy ML Dependencies: Self-contained and fast to install with minimal external dependencies.
Dual Transport Support: Usable as a standard Stdio MCP server or an optional standalone Express HTTP API.

Architecture

                       ┌──────────────────────┐
                       │   LLM Client         │
                       │ (Claude / Cursor)    │
                       └──────────┬───────────┘
                                  │ stdio (MCP Protocol)
                       ┌──────────▼───────────┐
                       │   bin/mcp-server.js  │
                       └──────────┬───────────┘
                                  │
                       ┌──────────▼───────────┐
                       │    luma_engine.js    │
                       └─────┬──────────┬─────┘
                             │          │
        ┌────────────────────┴──┐    ┌──┴────────────────────┐
        │ Keyword Search Vault  │    │  Luma Live REST API   │
        │ (vault/index.json)    │    │ (api.luma.com)        │
        └───────────────────────┘    └───────────────────────┘

Installation

Prerequisites

Node.js >= 18.0.0

Setup

git clone https://github.com/MegaGimen/lumaMCP.git
cd lumaMCP
npm install

Verify your setup by running the test suite:

npm test

MCP Client Configuration

1. Claude Desktop

Add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["/path/to/lumaMCP/bin/mcp-server.js"]
    }
  }
}

2. Cursor

In Cursor Settings -> Features -> MCP Servers, click Add New MCP Server:

Name: luma-mcp
Type: command
Command: node /path/to/lumaMCP/bin/mcp-server.js

Alternatively, add it to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "luma": {
      "command": "node",
      "args": ["/path/to/lumaMCP/bin/mcp-server.js"]
    }
  }
}

Tool Reference: `get_luma_events`

The server registers a single tool get_luma_events.

Input Parameters

Parameter	Type	Default	Description
`searchkeys`	string	`null`	Keywords to trigger title and content search over the event vault. When omitted, falls back to live API pagination.
`locations`	array of strings	`["san_francisco"]`	Target cities. Options: `'san_francisco'`, `'berkeley'`, `'new_york'`, `'palo_alto'`, `'san_jose'`, `'shanghai'`.
`categories`	array of strings	`[]`	Category filters. Options: `'tech'`, `'ai'`, `'crypto'`. Leave empty for all categories.
`start_date`	string	`null`	Start date filter in `MM:DD:YY` or `YYYY-MM-DD` format.
`end_date`	string	`null`	End date filter in `MM:DD:YY` or `YYYY-MM-DD` format.
`page`	integer	`1`	1-indexed page number for live pagination (when `searchkeys` is omitted).
`limit`	integer	`5`	Maximum number of events to return in search mode.

Example Tool Calls

Keyword Search

{
  "searchkeys": "autonomous agents hackathon",
  "locations": ["san_francisco", "berkeley"],
  "categories": ["ai", "tech"],
  "limit": 3
}

Live Pagination

{
  "locations": ["san_francisco"],
  "categories": ["tech"],
  "page": 1
}

Standalone HTTP API (Optional)

You can also run the service as an independent HTTP REST server:

npm start

Default port: 8004 (configurable via PORT environment variable).

Endpoints

GET /health: Returns service health and vault statistics.
GET /api/cities: Lists supported city identifiers and coordinate mappings.
GET /api/events: Fetches paginated live events in JSON.
GET /api/dump-markdown / POST /api/dump-markdown: Returns line-numbered Markdown for LLM ingestion.
POST /api/vault/search: Performs keyword title and content search over the local vault.
POST /api/vault/sync: Triggers background synchronization of upcoming events into the local vault.
GET /api/vault/status: Returns current synchronization status and cached event counts.

Contributing & License

Contributions are welcome. Feel free to open issues or submit pull requests.

This project is licensed under the MIT License. See LICENSE for details.

Luma MCP Server (luma-mcp)