# letterboxd-mcp

An MCP server that feeds a Letterboxd user's viewing history to LLMs, so the model can read what you watched and suggest new movies you'll actually like.

## Why RSS?

Letterboxd has no official public API. The per-user RSS feed (`https://letterboxd.com/{username}/rss/`) is the only sanctioned machine-readable surface, so this server parses it. No scraping, no login.

**Note**: the feed only holds the ~50 most recent diary entries.

## Tools

| Tool | Returns |
|------|---------|
| `get_diary(username)` | Recent entries: film, year, rating, liked, rewatch, watched date, review text, TMDB id |
| `get_reviews(username)` | Same, but only entries with written review text |

## What it needs

Films must be in your diary for the feed to pick them up. Star-rating a film on its page doesn't count; it never reaches the feed. Use the Log/Review flow instead and set your rating there. Review text optional.

Written reviews still help, even a single line. A rating tells the model what you watched. A review tells it why you liked or hated it, and that second part is what makes its suggestions any good.

## Setup

Requires [uv](https://docs.astral.sh/uv/).

```sh
uv sync
uv run python test_server.py   # self-check against bundled fixtures
uv run python smoke.py <your_username>  # live end-to-end check
```

## MCP client registration

```json
{
  "mcpServers": {
    "letterboxd": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/letterboxd-mcp", "python", "server.py"]
    }
  }
}
```