Lightning FM :: MCP Server

An MCP server for Lightning FM's music catalog: search tracks, look up artists, and check what's live on the station, all from an agent.

There is no separate agent API. This server reads exactly what a human client reads: kind 31337 track events and kind 0 profiles from public Nostr relays, audio and images from the public Blossom server, and the kind 30311 live activity event the station publishes on every track change. Every track is signed by the artist's own key. This is the canonical catalog, not a curated subset the platform maintains for agents. Artists keep their exit rights: the catalog lives in events they signed, and nothing this server returns depends on the platform's goodwill.

Who this is for

• Agent developers: you want the tools in your MCP client. Go to Use it and Tools. No install, no API key, no account.
• Contributors: you want to change or extend the server. Go to What works today and Development. The wire format this server parses is documented at lightning.fm/interop.

Use it

Add it to your MCP client's server config. For Claude Code or Claude Desktop:

{
  "mcpServers": {
    "lightning-fm": {
      "command": "npx",
      "args": ["-y", "lightning-fm-mcp"]
    }
  }
}

No install, no API key, no account. It talks to relay.lightning.fm and media.lightning.fm by default. See Configuration to point it elsewhere.

Tools

• search_catalog: free-text search plus genre/tag filters over the full catalog. Leave every filter empty to browse newest-first.
• get_artist: look up an artist by display name (partial match), hex pubkey, or npub. Returns their profile and full discography.
• get_now_playing: what's currently on air, and the stream URL.

What works today

Verified against src/, not against ambition.

Configuration

All environment variables are optional; defaults point at production. Nothing here is a secret. This server is read-only and never signs or publishes anything.

What this sends

Nothing about you, ever. This server has no telemetry, no analytics, no phone-home, and no opt-in flag for any of the above. It reports nothing to Lightning FM.

The one thing it does send is a User-Agent header on its outbound relay connections:

User-Agent: lightning-fm-mcp/<version>

That is the software naming itself. It is byte-identical for every install, contains no identifier, and says nothing about you or your machine. Without it the underlying websocket library sends its own default User-Agent instead, so this replaces one generic string with a specific one; it does not add a channel. It exists so Lightning FM can tell agent catalog queries apart from browser traffic in its own relay logs.

If you would rather not send it, npm and a one-line edit to src/config.ts are all it takes. It is a measurement aid, not a control.

Development

npm install
npm run dev     # runs src/index.ts directly via tsx
npm run build   # tsc, emits dist/
npm test        # tsx --test tests/*.test.ts

Layout

• src/index.ts server entry, stdio transport
• src/tools.ts the three MCP tool registrations
• src/nostr/ relay reads: catalog.ts, profiles.ts, now-playing.ts, and track.ts (kind 31337 parsing)
• src/config.ts env handling and defaults
• tests/ parsing and catalog tests

src/nostr/track.ts mirrors the kind 31337 parsing in station-server/src/catalog/track.ts (private repo) and app-desktop/src-tauri/src/relay.rs. All three must agree on tag names. This is the platform's public wire format, documented in full at lightning.fm/interop.

License

MIT