mcp-metacritic

# mcp-metacritic

[![npm](https://img.shields.io/npm/v/mcp-metacritic.svg)](https://www.npmjs.com/package/mcp-metacritic)
[![CI](https://github.com/smeet666/mcp-metacritic/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-metacritic/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-metacritic.svg)](./LICENSE)

An [MCP](https://modelcontextprotocol.io) server for
[Metacritic](https://www.metacritic.com). Search films, shows and games, read
Metascores and audience scores, and quote what individual critics wrote, with
the publication named and the article linked. **No API key, no account, no
configuration.**

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

---

## Quickstart

**One-click install**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=metacritic&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tZXRhY3JpdGljIl19)
[![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=metacritic&config=%7B%22name%22%3A%22metacritic%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-metacritic%22%5D%7D)

**Claude Code**

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

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

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

**Bundle, without npm**

Download `mcp-metacritic-<version>.mcpb` from
[the latest release](https://github.com/smeet666/mcp-metacritic/releases/latest) and open
it. A client that supports MCP bundles installs it on its own, with no npm and
no configuration file to edit. The bundle carries its dependencies, so nothing
is fetched at install time.

## Tools

| Tool            | What it does                                                | Key parameters                                    |
| --------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| `search_titles` | Finds films, shows and games by title. Compact rows.        | `query`, `kind`, `limit`                          |
| `get_title`     | Reads one entry, section by section.                        | `slug`, `kind`, `sections`, `max_chars`, `offset` |
| `get_reviews`   | Individual critic or audience reviews, filtered by verdict. | `slug`, `kind`, `source`, `sentiment`, `limit`    |
| `browse_titles` | Rankings: best rated, newest, most looked at.               | `kind`, `sort`, `genre`, `limit`, `offset`        |

Search returns a `slug` and a `kind` for every result, and the other tools take
both. That is the intended chain: search, then read.

The server is **read-only**. It writes nothing back to Metacritic.

### Things worth knowing

**The two scores are on different scales.** The critic Metascore runs to 100 and
the audience score to 10, so 73 and 8.9 describe similar opinions. Every score
this server returns carries its own `max`, and the tool descriptions say so,
because averaging the two is the single easiest mistake to make with this data.

**Sections are opt-in because an entry is large.** A detail response is 46 KB
for a film, most of it artwork variants. `get_title` returns `basic` and
`scores` by default; `awards`, `production`, `networks` and `where_to_watch`
cost an extra request each and are only fetched when asked for.

**Reviews are a sample, not a page.** Metacritic counts 36 critic reviews on a
given film and serves 7 through this route, whatever paging you ask for. The
tool says so rather than presenting the sample as the whole list, and links the
entry page where the rest can be read.

**A failure is never an empty result.** Every response carries either a `data`
object or an `errors` array, and this server reads that distinction rather than
guessing. A missing entry produces an error with a code; a request that could
not be made says it could not be made, and never that Metacritic publishes
nothing. Those are very different answers and a model cannot tell them apart on
its own.

**Search matches titles, and nothing else.** It cannot find an entry from a
plot detail, a person or a studio, it cannot page, and for a multi-word query
the site counts matches loosely: "the matrix" reports over 55 000 entries
because it counts anything matching either word.

**Browse paging is approximate.** Metacritic does not order tied entries
stably, so an entry can appear on two consecutive pages. Deduplicate by slug
rather than counting rows.

## Configuration

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

| Variable                 | Default                              | Purpose                                                        |
| ------------------------ | ------------------------------------ | -------------------------------------------------------------- |
| `MC_USER_AGENT`          | `mcp-metacritic v<version> (<repo>)` | User-Agent sent to Metacritic.                                 |
| `MC_MIN_INTERVAL_MS`     | `1000`                               | Minimum gap between requests. Values below 500 ms are ignored. |
| `MC_TIMEOUT_MS`          | `15000`                              | Per-request timeout.                                           |
| `MC_MAX_RETRIES`         | `3`                                  | Retries on refusals and transient errors.                      |
| `MC_CACHE_TTL_MS`        | `86400000`                           | Catalogue cache lifetime (24 hours).                           |
| `MC_SCORES_CACHE_TTL_MS` | `3600000`                            | Scores and reviews cache lifetime (1 hour).                    |
| `MC_CACHE_MAX_ENTRIES`   | `200`                                | In-memory cache size.                                          |
| `MC_LOG_LEVEL`           | `error`                              | `silent`, `error`, `info` or `debug`. Logs go to stderr.       |

A User-Agent claiming to be a browser has the project's own identity appended
to it, so the traffic stays attributable whatever a caller sets.

## How it works

Metacritic's website is served by a JSON backend at
`backend.metacritic.com`, and this server calls the same routes its own pages
call. It sends one request at a time, paces itself, backs off when refused, and
keeps two in-memory caches: a day for catalogue entries, which change when
someone edits them, and an hour for scores and reviews, which move as reviews
land.

Streaming links arrive wrapped in click-tracking redirects of around 800
characters, with the real destination inside. This server unwraps them: you get
the provider's own URL, not a tracker.

### On the terms of use

`metacritic.com/terms-of-use/` returns 404, so the terms could not be read.
This is worth stating plainly rather than leaving implicit.

What is verifiable: the backend host serves no `robots.txt` at all, requires no
API key, and did not throttle ten consecutive requests during testing. Those
are the conditions this server operates under, and it does not take them as
permission to be greedy. It sends one request per second at most, identifies
itself, caches what it reads, and carries a link back to Metacritic on every
result, including on every quoted review.

If Metacritic would rather it did not exist, opening an issue is enough.

## Development

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

Fixtures are generated, not captured: every title, quote, publication and
studio in `test/fixtures` is invented, so the tests are deterministic and no
third-party content lives in this repository.

The API layer (`src/mc`) does not import the MCP SDK and is published
separately as `mcp-metacritic/client`, so it can be used as a plain library. It
enforces the pacing floor and the identifying User-Agent itself, so those hold
for a library consumer too.

## Reviews, scores and copyright

Metascores, review texts and the editorial work behind them belong to
Metacritic and to the publications it aggregates. This project claims no rights
over them and ships none of their content.

Review quotes are returned as excerpts, capped in length, always with the
publication named and with a link to the original article where the site
provides one. If you repeat a quote, keep both. If you cite a score, credit
Metacritic and link the entry: every result carries a `source_url`.

This is an unofficial project, with no affiliation to or endorsement by
Metacritic or Fandom.

## Contributing

Bugs, questions and ideas all belong in
[the issue tracker](https://github.com/smeet666/mcp-metacritic/issues). Pull requests
are welcome; please open an issue first so we can agree on what the right
answer is before you write it. [CONTRIBUTING.md](CONTRIBUTING.md) has the
detail, and [SECURITY.md](SECURITY.md) covers anything exploitable.

## Support

These servers are free and stay free. If one of them saved you an afternoon,
you can [buy me a coffee](https://buymeacoffee.com/smeet666).

## License

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

---

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

# mcp-metacritic (français)

Un serveur [MCP](https://modelcontextprotocol.io) pour
[Metacritic](https://www.metacritic.com). Cherchez des films, séries et jeux,
lisez les Metascores et les notes du public, et citez ce qu'ont écrit les
critiques, avec la publication nommée et l'article lié. **Sans clé d'API, sans
compte, sans configuration.**

## Démarrage rapide

**Installation en un clic**