mcp-lyricscom

# mcp-lyricscom

[![npm](https://img.shields.io/npm/v/mcp-lyricscom.svg)](https://www.npmjs.com/package/mcp-lyricscom)
[![CI](https://github.com/smeet666/mcp-lyricscom/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-lyricscom/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-lyricscom.svg)](./LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-lyricscom)

An [MCP](https://modelcontextprotocol.io) server for [lyrics.com](https://www.lyrics.com).
Search songs by a word in their lyrics, by title, and read the full text.
**No API key, no account, no configuration.**

_(Version française plus bas / [French version below](#mcp-lyricscom-français))_

---

## Quickstart

**One-click install**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=lyricscom&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1seXJpY3Njb20iXX0%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=lyricscom&config=%7B%22name%22%3A%22lyricscom%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-lyricscom%22%5D%7D)

**Claude Code**

```bash
claude mcp add lyricscom -- npx -y mcp-lyricscom
```

**Claude Desktop, Cursor, and any client using the standard config format**

```json
{
  "mcpServers": {
    "lyricscom": {
      "command": "npx",
      "args": ["-y", "mcp-lyricscom"]
    }
  }
}
```

That is the whole setup. There is nothing to sign up for.

## Tools

| Tool            | What it does                                                                                 | Key parameters                                        |
| --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `search_lyrics` | Finds songs whose **lyrics contain a word or phrase**, with the matching line as an excerpt. | `query`, `limit`, `page`, `verify`, `include_excerpt` |
| `search_songs`  | Finds songs **by title**, optionally narrowed by artist.                                     | `title`, `artist`, `limit`, `page`, `match`           |
| `get_lyrics`    | Reads the **full lyrics** of one song, by id or URL.                                         | `id`, `url`, `max_chars`, `offset`, `highlight`       |

The two search tools return a lyrics.com `id` for every result; `get_lyrics` takes that id.
That is the intended chain: search, then read.

### Things worth knowing

**Search really checks the lyrics.** lyrics.com's own search also returns title
matches and loose matches. `search_lyrics` filters them out locally, using a
word-boundary matcher, so a result is a song where the word genuinely appears.
`coup` does not match `beaucoup`, but `enfant` does match `enfants`. Set
`verify: "none"` to see the raw, unfiltered list.

**Pagination is yours to drive.** One call fetches one page (24 rows on
lyrics.com). The response carries `has_more` and `next_page`. Raising `limit`
does not fetch more pages, on purpose: chaining several fetches inside a single
tool call is the fastest way to get rate limited.

**Some songs have no lyrics.** A valid lyrics.com page can simply have no text
on file. That comes back as `status: "no_lyrics"` with a successful result, not
an error, so there is nothing to retry.

**Rate limiting is visible, not silent.** lyrics.com answers a throttled request
with an empty body rather than a normal error code. This server detects that and
returns an explicit `throttled` error telling you to wait and try again. It never
reports throttling as "no results found", which would be indistinguishable from a
genuine answer.

## Configuration

Every variable is optional. Set them in the `env` block of your MCP client config.

| Variable                      | Default                               | Purpose                                                                                                   |
| ----------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `LYRICSCOM_USER_AGENT`        | `mcp-lyricscom/<version> (+repo url)` | User-Agent sent to lyrics.com. See below.                                                                 |
| `LYRICSCOM_MIN_INTERVAL_MS`   | `1100`                                | Minimum gap between requests. Raise it if you hit throttling. Values below 500 ms are ignored, see below. |
| `LYRICSCOM_TIMEOUT_MS`        | `15000`                               | Per-request timeout.                                                                                      |
| `LYRICSCOM_MAX_RETRIES`       | `3`                                   | Retries on throttling and transient errors.                                                               |
| `LYRICSCOM_CACHE_TTL_MS`      | `900000`                              | In-memory page cache lifetime (15 minutes).                                                               |
| `LYRICSCOM_CACHE_MAX_ENTRIES` | `200`                                 | In-memory page cache size.                                                                                |
| `LYRICSCOM_LOG_LEVEL`         | `error`                               | `silent`, `error`, `info` or `debug`. Logs go to stderr.                                                  |

```json
{
  "mcpServers": {
    "lyricscom": {
      "command": "npx",
      "args": ["-y", "mcp-lyricscom"],
      "env": { "LYRICSCOM_MIN_INTERVAL_MS": "1500" }
    }
  }
}
```

### About the User-Agent

This server identifies itself honestly by default, naming the project and linking
to this repository. lyrics.com serves that fine today.

It does block some generic tool agents outright: a plain `curl/8.5.0` gets a 403.
If you ever see a `blocked_user_agent` error, set `LYRICSCOM_USER_AGENT` to a
value of your choosing. That override exists so you are not stuck, and what you
put in it is your call and your responsibility.

## Troubleshooting

**"throttled" errors.** lyrics.com is rate limiting you. The server already
retries with backoff and slows itself down on its own, so seeing this error means
those retries were exhausted. Once the site starts throttling, the window
commonly lasts several minutes, not seconds: wait a minute or more before trying
again, and raise `LYRICSCOM_MIN_INTERVAL_MS` if it keeps happening. A `throttled`
error does not mean your query has no results.

**"blocked_user_agent" errors.** See the User-Agent section above.

**"parse_failure" errors.** lyrics.com changed its page layout and the server
could not read the response. Please [open an issue](https://github.com/smeet666/mcp-lyricscom/issues)
with the query you used. The server deliberately reports this loudly instead of
pretending it found nothing.

**Empty results.** If `raw_result_count` is greater than zero while `results` is
empty, lyrics.com did return rows but none of them actually contain your word.
Try `verify: "none"` to see them anyway.

## How it works

There is no lyrics.com API. The server requests the same public pages you would
open in a browser and reads them with [cheerio](https://cheerio.js.org). It
fetches one page at a time, roughly one request per second, backs off when the
site pushes back, and keeps a small in-memory cache so repeated questions about
the same song do not hit the site again.

## Development

```bash
npm install
npm run build:fixtures   # regenerate the HTML test fixtures
npm test                 # unit tests, no network
npm run typecheck
npm run build
LYRICSCOM_LIVE=1 npm run test:live   # hits the real site, excluded from CI
npm run inspector        # explore the tools in the MCP Inspector
```

The fixtures are generated, not scraped: they reproduce lyrics.com's markup
structure with placeholder text, so the parser tests are deterministic and no
copyrighted lyrics live in this repository.

The scraping layer (`src/lyricscom`, `src/text`) does not import the MCP SDK and
is published separately as `mcp-lyricscom/client`, so it can be used as a plain
library.

## Lyrics and copyright

Song lyrics are copyrighted works owned by their authors and publishers. This
project claims no rights over them.

This server is a client. It fetches the same public lyrics.com pages you could
open in a browser, on demand, one request at a time, in response to an explicit
request from you or your assistant. It does not crawl the site, does not build a
lyrics database, and does not write anything to disk. Pages are held in memory
for a few minutes so that repeated questions do not hit the site again.

Every result carries the artist, the title, and the source URL. If you display or
reuse anything this server returns, keep that attribution and link back to the
source page.

The server honours lyrics.com's robots.txt: none of the endpoints it uses are
disallowed there, and it paces itself to roughly one request per second. That
pacing is enforced: `LYRICSCOM_MIN_INTERVAL_MS` is refused below 500 ms, and a
lower value falls back to the standard interval with a warning on stderr. Raise
it to slow the client down further.

This is an unofficial project, with no affiliation to, endorsement by, or
sponsorship from lyrics.com or STANDS4 Ltd. Use it in accordance with lyrics.com's
terms of service and the copyright law that applies to you.

## License

MIT. See [LICENSE](./LICENSE). The license covers this source code only, not the
lyrics retrieved through it.

---

<a name="mcp-lyricscom-français"></a>

# mcp-lyricscom (français)

Un serveur [MCP](https://modelcontextprotocol.io) pour [lyrics.com](https://www.lyrics.com).
Cherchez des chansons par un mot présent dans les