lightning-fm-mcp
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., "@lightning-fm-mcp What's currently playing on Lightning FM?"
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.
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.
Related MCP server: Maximum Sats MCP
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.
Feature | Status |
| Works |
| Works |
| Works |
Read-only guarantee: the server holds no keys, never signs, never publishes; there are no write tools | Works, by construction |
Relay snapshot caching (default 60s TTL) so repeated tool calls don't hammer relays | Works |
Transport | stdio only; no HTTP transport yet |
Writes of any kind (publishing tracks, zapping, tipping) | Not built, and out of scope by design |
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.
Variable | Default | What it does |
|
| Comma-separated relay URLs to query. Only add a relay here if it gates writes the way relay.lightning.fm does. Kind 31337 isn't exclusive to Lightning FM, and an unrestricted public relay hands back every other app's tracks too. |
|
| Blossom server audio/image hashes resolve against. |
|
| How long a fetched snapshot is reused before the next tool call re-queries the relays. |
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.tsLayout
src/index.tsserver entry, stdio transportsrc/tools.tsthe three MCP tool registrationssrc/nostr/relay reads:catalog.ts,profiles.ts,now-playing.ts, andtrack.ts(kind 31337 parsing)src/config.tsenv handling and defaultstests/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
Available Tools
3 toolsget_artistLook up a Lightning FM artistA
Look up an artist by display name or Nostr pubkey (hex or npub) and return their profile plus every track they have published to Lightning FM.
Inputs: artist (required).
get_now_playingWhat's playing on Lightning FM right nowA
Read the current live activity (NIP-53, kind 30311) Lightning FM publishes on every track change: the track currently on air, the stream URL, and station status.
Inputs: no named parameters.
search_catalogSearch Lightning FM catalogA
Search or browse Lightning FM's Nostr-native music catalog (kind 31337 track events, fetched live from wss://relay.lightning.fm). Every result is signed by the artist's own Nostr key — this is the canonical catalog, not a curated subset. Leave all filters empty to browse the whole catalog, newest first.
Inputs: tag, genre, limit, query.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct purpose: searching the catalog, looking up an artist, and reading live now-playing data. There is no practical overlap in what an agent would select them for.
All three tools follow a clear verb_noun convention: search_catalog, get_artist, get_now_playing. The naming pattern is predictable and consistent.
Three tools is a tight, well-scoped set for a read-only music catalog API. Each tool covers a distinct high-level user need without unnecessary bloat.
The core domain is covered: catalog browsing/search, artist lookup with tracks, and live playback status. A direct track-by-ID detail lookup is a minor gap, but the other tools can work around it through search or artist queries.
Related MCP Connectors
Music industry tools for AI agents: artist research, catalogs, release plans and content.
Find Bizzy radio stations, read station cards and public author information. Read-only; no playback.
Generate full songs with vocals, instrumentals and sound effects from text. One server for Suno, Google Lyria, Mureka, MiniMax, ACE-Step, YuE and ElevenLabs. Your agent can quote the credit cost before generating, start a song, wait for it to finish and return download links. Sign in with OAuth; optional daily credit caps; retries never charge twice.
Public music-rights directory: who wrote and owns a song, its ISWC/ISRC/IPI, and licensing asks
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables interaction with Last.fm music data including searching for artists, albums, and tracks, accessing user listening history, and managing music preferences. Supports both read-only operations and authenticated write operations like scrobbling and loving tracks.345-
- AlicenseAqualityDmaintenanceProvides tools for AI agents to access Bitcoin, Lightning Network, and Nostr knowledge, including real-time network statistics and Web of Trust reputation data. It features an integrated Lightning Network payment system for micro-transactions and query-based interactions.126 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to query the MusicBrainz music database for artists, albums, recordings, and labels. It provides tools for advanced searches, detailed metadata retrieval, and accessing cover art information.1713GPL 3.0
- AlicenseBqualityDmaintenanceEnables AI agents to access public Spotify data (tracks, albums, artists, playlists, podcasts) without an API key, including lyrics and podcast transcripts with optional login.282,216 PyPI327MIT