Skip to main content
Glama

lyricmood

A personal, lyrics-aware music assistant. Ask it why you like a song, what the lyrics actually say (including in languages you don't speak well), which songs feel like this one lyrically, or for a playlist that moves from sad to hopeful.

lyricmood has no chat UI of its own. It's a set of tools you can use from any LLM client:

  • MCP server: use Claude Code, Codex, Gemini CLI or Claude Desktop as the chat interface. See Use it from an MCP client.

  • Terminal chat (lyricmood chat, coming in milestone 5): a chat in your terminal with a swappable LLM backend. The first backend is your own Claude Code (no API key). An API backend (LiteLLM: OpenRouter, Gemini, OpenAI, Anthropic) can be added later.

Both read the same tool registry, so every tool is defined once.

Status: milestones 1–4 and 6 of 7 done; 5 (terminal chat) is next. Spotify search, lyrics (LRCLIB), audio features (ReccoBeats), Last.fm tags, artist top tracks, the song you're playing now, lyrics-based similar songs, artist comparisons, your top and liked songs, mood playlists and playlist editing, all available to MCP clients. See Roadmap.

Why this exists

Plenty of Spotify MCP servers exist (playback control, playlist CRUD, a few that fetch lyrics for one track). None of them combine lyrics, mood features and tags to answer "what is this song about, and why do I like it?", or rank songs by lyrical similarity. Existing lyrics-similarity projects are mostly notebooks over static Kaggle datasets. lyricmood is built around three things they lack:

  • understanding lyrics for a non-native speaker

  • lyric-based discovery that only embeds tracks when they come up as candidates, never a whole catalog

  • working with whatever LLM you already use

Related MCP server: Mr. Magic MCP Server

Setup

Requires uv. uv installs Python 3.12 itself if you don't have it.

git clone https://github.com/yigitates17/lyricmood.git
cd lyricmood
uv sync --extra embeddings   # or plain `uv sync`, see below
cp .env.example .env

The embeddings extra adds what find_similar_by_lyrics needs: ONNX Runtime, Hugging Face tokenizers, and LanceDB. That's about 385 MB on top of the base install's ~215 MB. The first similarity search also downloads the lyrics model, intfloat/multilingual-e5-small, once: about 480 MB, into ~/.lyricmood/models. It runs on CPU through ONNX, so PyTorch is not needed. Leave the extra out if you only want lyrics explanations, profiles and playlists. Everything else works, and the similarity tool will say how to enable it.

Spotify (required)

Spotify's Web API now requires the app owner to have Premium, and Development Mode apps are limited to 5 users. Both are fine for personal use.

  1. Open the Spotify Developer Dashboard and log in with your Premium account. Accept the developer terms if asked.

  2. Click Create app and fill in:

    • App name: lyricmood (anything works)

    • App description: Personal lyrics-aware music assistant

    • Redirect URIs: enter http://127.0.0.1:8888/callback and click Add. Use 127.0.0.1, not localhost; Spotify rejects localhost.

    • Which API/SDKs are you planning to use?: tick Web API.

    • Accept the terms and click Save.

  3. Open the app, go to Settings, and copy the Client ID into .env:

    SPOTIFY_CLIENT_ID=your_client_id_here

    You don't need the Client Secret. lyricmood logs in with PKCE, which is designed for apps that can't keep a secret.

  4. Log in:

    uv run lyricmood auth spotify

    Your browser opens Spotify's consent page. Click Agree. The browser then shows "Authentication successful" and the terminal prints Spotify: logged in. The token is saved to ~/.lyricmood/spotify_token.json and refreshes automatically.

If it doesn't work:

  • INVALID_CLIENT: Invalid redirect URI: the URI in .env must match the dashboard character for character, including /callback and no trailing slash.

  • Address already in use: something else is using port 8888. Pick another port, say 8899, and change it in both the dashboard and SPOTIFY_REDIRECT_URI.

  • 403 "user not registered": in the dashboard, go to User Management and add the email of your Spotify account.

  • "Spotify session expired" after several months: Spotify refresh tokens now last six months. Run uv run lyricmood auth spotify again.

The login asks for all the permissions lyricmood will eventually need (top tracks, saved tracks, reading and editing playlists, the currently playing song), so later milestones won't make you log in again.

Last.fm provides mood and genre tags, artist top tracks and, later, similar songs. Without a key, get_track_profile leaves out tags and get_artist_tracks falls back to Spotify's search order.

  1. Go to https://www.last.fm/api/account/create (log in or create a free account).

  2. Fill in Application name (e.g. lyricmood). The other fields can stay empty.

  3. Copy the API key (not the shared secret) into .env:

    LASTFM_API_KEY=your_key_here

LRCLIB and ReccoBeats

Neither needs a key. lyricmood sends a User-Agent that identifies it, as LRCLIB asks.

YouTube

This comes with milestone 7.

Usage

uv run lyricmood status                         # keys, login state, cache size
uv run lyricmood tools                          # list tools
uv run lyricmood tools --schema                 # ...with JSON input schemas
uv run lyricmood call search_track query="nemo nightwish"
uv run lyricmood call search_track query="artist:Nightwish" limit=10
uv run lyricmood call search_track query="https://open.spotify.com/track/..."
uv run lyricmood call get_track_profile track="Carnival of Rust Poets of the Fall"
uv run lyricmood call get_lyrics track=2DtPEKs3Pj7E06EoWW4vw8
uv run lyricmood call get_artist_tracks artist="Haloo Helsinki!" limit=5
uv run lyricmood call now_playing                # play something on Spotify first
uv run lyricmood call now_playing with_profile=false
uv run lyricmood call find_similar_by_lyrics track=2DtPEKs3Pj7E06EoWW4vw8 k=8
uv run lyricmood call find_similar_by_lyrics track=2DtPEKs3Pj7E06EoWW4vw8 mood_weight=0.4
uv run lyricmood call find_similar_by_lyrics track="Nemo Nightwish" expand_pool=false
uv run lyricmood call analyze_artists --json '{"artists": ["Poets of the Fall", "Nightwish"]}'
uv run lyricmood call get_my_top_tracks time_range=short_term limit=10
uv run lyricmood call get_my_playlists
uv run lyricmood call build_mood_playlist --json '{"mood_text": "heartbreak, lonely nights", "valence": 0.2, "energy": 0.35, "seed_artists": ["Nightwish"], "size": 10}'
uv run lyricmood call build_mood_playlist --json '{"mood_text": "-", "size": 10, "arc": [{"mood_text": "despair, loss", "valence": 0.15}, {"mood_text": "hope, light after the storm", "valence": 0.75}]}'

call runs any tool directly and prints exactly the JSON an LLM would get. It's the quickest way to test a tool without an LLM.

Your data (SQLite cache, Spotify token, lyrics vectors, the model) lives in ~/.lyricmood. It sits outside the repo on purpose: MCP clients start the server from whatever directory they like, and they all need to share one cache. Set LYRICMOOD_DATA_DIR to move it.

Use it from an MCP client

The MCP server (lyricmood-mcp) exposes every tool over stdio. It finds .env and ~/.lyricmood by itself, so clients need no environment variables. Before registering it:

cd ~/lyricmood
uv sync --extra embeddings
uv run lyricmood auth spotify      # the server can't open a login prompt itself
uv run lyricmood download-model    # so the first similarity search doesn't
                                   # spend a tool call downloading 480 MB

Every example below points at the server binary inside the project's virtualenv. Replace $HOME/lyricmood if you cloned somewhere else. A direct path works no matter which directory the client starts in, needs no extra flags, and starts in about half a second. Re-run uv sync --extra embeddings after pulling updates.

Claude Code

claude mcp add -s user lyricmood -- "$HOME/lyricmood/.venv/bin/lyricmood-mcp"
claude mcp list                    # should show: lyricmood ... ✓ Connected

-s user makes it available in every project. Inside Claude Code, /mcp lists the tools. Try "What is Carnival of Rust by Poets of the Fall about?" or "Explain the song I'm playing right now."

Codex CLI

codex mcp add lyricmood -- "$HOME/lyricmood/.venv/bin/lyricmood-mcp"

Codex stops tool calls after 60 s by default, and a song's first find_similar_by_lyrics can take about a minute. Raise the limit in ~/.codex/config.toml:

[mcp_servers.lyricmood]
command = "/Users/you/lyricmood/.venv/bin/lyricmood-mcp"
tool_timeout_sec = 180

Gemini CLI

gemini mcp add -s user lyricmood "$HOME/lyricmood/.venv/bin/lyricmood-mcp"

Use -s user. Gemini refuses project-scoped config in folders it doesn't trust.

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json and restart the app:

{
  "mcpServers": {
    "lyricmood": {
      "command": "/Users/you/lyricmood/.venv/bin/lyricmood-mcp"
    }
  }
}

The desktop app has been reported to cancel tool calls after about 60 s. If a first similarity search fails there, run it once from the terminal (uv run lyricmood call find_similar_by_lyrics track=...) to fill the cache, then ask again.

The server also sends the client short instructions: the user may not be a native speaker, so explain idioms and translate key lines; "this song" means now_playing; and mention missing data instead of guessing.

Tools

Tool

Milestone

Status

search_track(query, limit)

1

✅

get_lyrics(track)

2

✅

get_track_profile(track)

2

✅

get_artist_tracks(artist, limit)

2

✅

now_playing(with_profile)

2

✅

find_similar_by_lyrics(track, k, expand_pool, mood_weight)

3

✅

analyze_artists(artists, tracks_per_artist)

3

✅

get_my_top_tracks(time_range, limit)

6

✅

get_saved_tracks(limit, offset)

6

✅

get_my_playlists(limit, offset)

6

✅ (added: needed to find playlist IDs)

get_playlist_tracks(playlist, limit)

6

✅ (added: needed before reordering)

build_mood_playlist(mood_text, valence, energy, seed_artists, size, arc, …)

6

✅

create_spotify_playlist(name, tracks, description, public)

6

✅

update_spotify_playlist(playlist_id, add, remove, reorder)

6

✅

convert_playlist

7

planned

Every track argument takes a Spotify ID, URL or URI, or free text, which resolves to the top search hit.

get_track_profile returns, in one call:

  • the lyrics (cut at a stanza boundary past 2,500 characters) and simple stats. repeated_lines usually marks the chorus.

  • ReccoBeats audio features: valence (musical positivity), energy, danceability, acousticness, tempo and key.

  • Last.fm tags. Last.fm rarely tags individual songs, so the artist's tags are often used instead; tags_source says which.

Each source can fail on its own (ReccoBeats in particular is flaky). The profile still comes back, with a missing field saying what's absent and why. The LLM interprets the lyrics; the code only gathers facts.

Lyrics matching: artist + title decide the match; duration only breaks ties. lyricmood tries LRCLIB /api/get with artist, title and duration first. If that misses, it searches and takes the entry whose artist and title match (fuzzy), choosing the closest length and preferring entries with lyrics over ones flagged instrumental. Length never rejects a match, because plain lyrics are the same across remasters, compilations and radio edits. Length only matters for synced (timestamped) lyrics, which lyricmood doesn't use. Version suffixes ("- Remastered 2004", "(feat. X)") are stripped before lookup. "Live" and "Orchestral Version" are kept, because their lyrics can differ or be missing. Lyrics are cached forever; misses are retried after 14 days.

find_similar_by_lyrics finds songs whose lyrics are about similar things, across languages:

  1. It gathers about 40 candidates from Last.fm (similar tracks, the seed's top tags, similar artists' hits) and ReccoBeats recommendations, taking from each source in turn so no single one dominates.

  2. It resolves each candidate to Spotify and fetches its lyrics.

  3. It embeds the lyrics, one vector per stanza, with repeated choruses counted once and the song vector being their average. Vectors are stored in LanceDB, so a song is only ever embedded once.

  4. It ranks the candidates by similarity to the seed.

Each result includes matching_lines: the two passages, one from each song, that matched best. mood_weight (0–1) also favors songs with similar valence and energy. expand_pool=false skips the network and ranks only songs analyzed in earlier searches.

Scores are relative within one search (the best match is 1.0), not absolute. The first search for a song takes about a minute (mostly LRCLIB, which is rate-limited politely); repeats take under a second.

Known limitation: the model groups lyrics partly by language. An English song about loss can score close to an English party song. In a mixed English/Finnish test, the nearest neighbour was always the right topic, but scores aren't comparable across languages. See DESIGN §8.2.

build_mood_playlist proposes an ordered list. It doesn't save anything.

  • Where songs come from: the seed artists' top songs plus three similar artists each, or your own top and liked songs when no artists are given. The pool is about 60 songs (LYRICMOOD_MOOD_POOL_SIZE).

  • How each song is scored: half on lyrics, comparing mood_text against each song's stanzas, and half on music, how close its valence and energy are to the targets. feature_weight changes that split. Claude chooses the targets from your words, for example "sad" ≈ valence 0.2. A song missing lyrics or features counts as typical on that side, so missing data neither helps nor hurts it.

  • arc gives 2–5 stages, for example heartbroken → hopeful. Songs move through them gradually, with targets blended position by position.

  • max_per_artist keeps variety (default 3).

  • Mixed languages: give the mood in each language on separate lines, because the model favours lyrics in the query's language.

Playlist writes (create_spotify_playlist, update_spotify_playlist) change your Spotify account. New playlists are private by default, and their docstrings tell the LLM to confirm with you first. Your MCP client also asks before running a tool unless you've allowed it.

  • update_spotify_playlist works out the end state and checks it before writing anything, so a bad reorder changes nothing.

  • It refuses to reorder playlists that contain podcast episodes or local files, which a rewrite would drop.

  • It skips songs that are already in the playlist.

  • Spotify only lets apps read and edit your own (or collaborative) playlists.

analyze_artists samples each artist's top songs and returns:

  • lyric excerpts (opening stanza plus chorus, about 500 characters each)

  • average valence, energy, danceability and acousticness

  • Last.fm tags, plus the tags the artists share

The LLM reads the excerpts to find the common themes behind "why do I like these?". It doesn't need the embeddings extra.

Adding a tool

Put a module in lyricmood/tools/. Modules there are discovered automatically and show up in the MCP server, the chat and the CLI:

from pydantic import BaseModel
from lyricmood.context import AppContext
from lyricmood.registry import tool


class EchoInput(BaseModel):
    text: str


class EchoOutput(BaseModel):
    text: str


@tool
async def echo(ctx: AppContext, args: EchoInput) -> EchoOutput:
    """The docstring is the description the LLM sees."""
    return EchoOutput(text=args.text)

API clients live in lyricmood/core/ and must not contain LLM logic. Tools get those clients from ctx.

Development

uv sync --extra embeddings
uv run pytest            # offline: HTTP is mocked with respx + JSON fixtures
uv run ruff check . && uv run ruff format --check .

Similarity tests use a fake word-overlap embedder, so they're instant and need no model. tests/test_model_quality.py checks the real model on a small invented English/Finnish topic set. It runs only when the model is already downloaded, so CI skips it.

CI runs the same commands and never calls a real API. LRCLIB, Last.fm and ReccoBeats fixtures in tests/fixtures/ are recorded responses with images and country lists removed. All lyrics in them are replaced with invented text, because test data must never contain copyrighted lyrics. The Spotify fixtures are hand-built from Spotify's documented response shapes.

Spotify API constraints (2026)

Spotify's February 2026 changes for Development Mode apps shape the design:

  • Gone: recommendations, audio features, related artists (removed in 2024), artist top tracks, and batch GET /tracks?ids=. lyricmood gets audio features from ReccoBeats and similar tracks and artists from Last.fm.

  • Search returns at most 10 results per page. lyricmood paginates when asked for more.

  • ISRC (external_ids) was removed and then restored in March 2026. lyricmood treats it as optional.

  • Playlist contents are only returned for playlists you own. convert_playlist can't read other people's Spotify playlists.

docs/DESIGN.md explains the architecture, the reasoning behind it, and open questions.

Roadmap

  1. ✅ Skeleton, config, SQLite cache, Spotify OAuth, search_track

  2. ✅ LRCLIB, Last.fm and ReccoBeats clients, get_lyrics, get_track_profile, get_artist_tracks, now_playing

  3. ✅ Embeddings (multilingual-e5-small via ONNX) + LanceDB, find_similar_by_lyrics, analyze_artists

  4. ✅ MCP server exposing all tools (lyricmood-mcp)

  5. Terminal chat (lyricmood chat) with a swappable backend, starting with Claude Code, plus lyricmood watch, which summarizes each new song as it starts playing

  6. ✅ Top/liked songs, playlist create/update/read, build_mood_playlist (done before 5)

  7. YouTube client, convert_playlist

License

MIT

Available Tools

14 tools
analyze_artistsAnalyze ArtistsA

Sample each artist's most popular songs (lyrics excerpts, average audio mood, Last.fm tags) so you can find what they have in common, e.g. to answer "why do I like these artists?". Read the excerpts for recurring themes, imagery, perspective and emotional tone; use shared_tags and mood averages for the musical side.

Inputs: artists (required), tracks_per_artist.

build_mood_playlistBuild Mood PlaylistA

Pick and order songs for a mood, judging both what the lyrics are about (mood_text) and how the music feels (valence/energy targets you choose from the user's request). With arc, songs move gradually through 2-5 moods (e.g. heartbroken -> hopeful). Songs come from the seed artists and similar artists, or from the user's top and liked songs. This only proposes a list: show it to the user, then call create_spotify_playlist with the ids if they want it saved. The first run for new artists can take a minute or two.

Inputs: mood_text (required), arc, size, energy, +4 more.

create_spotify_playlistCreate Spotify PlaylistA

Create a new playlist in the user's Spotify account (private unless public is true) and add the given tracks in order. This changes the user's account: only call it after the user has agreed to the name and the track list.

Inputs: name (required), public, tracks, description.

find_similar_by_lyricsFind Similar By LyricsA

Find songs whose lyrics are about similar things as the given song (works across languages). Candidates come from Last.fm (similar tracks, tags, similar artists) and ReccoBeats, and are ranked by lyrics meaning with a local multilingual model. Scores are 0-1 relative to this search, not absolute. matching_lines shows the passages that matched best; use them to explain the connection. The first search for a song can take ~30-60 s; repeats are fast.

Inputs: track (required), k, expand_pool, mood_weight.

get_artist_tracksGet Artist TracksA

An artist's most popular tracks (by Last.fm listeners), resolved to Spotify. Falls back to Spotify search order when Last.fm has no data.

Inputs: artist (required), limit.

get_lyricsGet LyricsA

Get a song's plain lyrics (from LRCLIB) so you can translate, explain or interpret them. Long lyrics are cut at a stanza boundary (truncated: true). Use get_track_profile instead when mood or genre context also matters.

Inputs: track (required).

get_my_playlistsGet My PlaylistsA

Playlists in the user's Spotify library (own and followed). Only editable ones can be read song-by-song or changed: Spotify hides the contents of other people's playlists from apps since 2026.

Inputs: limit, offset.

get_my_top_tracksGet My Top TracksB

The user's most-played Spotify tracks over a time range, most played first. Good starting point for "why do I like what I like?".

Inputs: limit, time_range.

get_playlist_tracksGet Playlist TracksA

The songs of one of the user's own (or collaborative) playlists, in order. Needed before reordering or removing songs.

Inputs: playlist (required), limit.

get_saved_tracksGet Saved TracksA

The user's Liked Songs on Spotify, most recently liked first. total is the full count; page with offset.

Inputs: limit, offset.

get_track_profileGet Track ProfileA

Everything about one song in a single call: lyrics (possibly truncated) with simple stats (repeated lines usually mark the chorus), audio features from ReccoBeats (valence = musical positivity, energy, danceability, acousticness, tempo, key), and Last.fm mood/genre tags. Any source can be missing; missing says which and why. Use this to explain what a song is about or why someone might like it.

Inputs: track (required).

now_playingNow PlayingA

The song currently playing on the user's Spotify, with its profile (lyrics, audio features, tags) so you can explain it right away. Use it when the user says "this song", "what's playing", etc.

Inputs: with_profile.

search_trackSearch TrackA

Search Spotify for tracks. Returns compact track info (id, title, artists, album, year, duration, isrc). Use the returned id to refer to a track in other tools. A Spotify link or ID returns exactly that track.

Inputs: query (required), limit.

update_spotify_playlistUpdate Spotify PlaylistA

Change one of the user's own playlists: remove tracks, append tracks (ones already in it are skipped), and/or set a completely new order, in that sequence. This changes the user's account: confirm with the user first.

Inputs: playlist_id (required), add, remove, reorder.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target distinct resource+action pairs, and the potentially confusing trio (get_lyrics vs get_track_profile vs now_playing) is explicitly disambiguated in the descriptions (plain lyrics vs full profile vs currently playing). The propose-vs-save split between build_mood_playlist and create_spotify_playlist is also clean. Only minor residual overlap remains, so an agent rarely misselects.

    Naming Consistency4/5

    Names follow a consistent snake_case verb_noun pattern (get_*, create_*, update_*, build_*, find_*, search_*, analyze_*). The lone deviation is `now_playing`, which is a state noun rather than a verb_noun action. The convention is otherwise very predictable.

    Tool Count5/5

    Fourteen tools sit comfortably in the well-scoped 3-15 range, and each one maps to a distinct capability (library reads, discovery, lyrics analysis, playlist writing). No tool feels redundant or padded.

    Completeness4/5

    The surface covers the core lifecycle: search/profile/lyrics, discovery via similar-by-lyrics and mood playlists, reading the user library, and creating/updating playlists. Gaps include no playlist deletion or unfollow and no dedicated album/artist-profile lookup, but agents can work around these for the stated lyric+mood purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Spotify control and synchronized lyrics retrieval that enables playback management, queue navigation, and music search capabilities. It also features perception tools for real-time track analysis, including BPM, key detection, and timestamped lyrics.
      3
      Apache 2.0