letterbox-buddy 0.1.1

An MCP server that turns your rough movie notes into polished reviews and tracks your watch history

letterbox-buddy

An MCP server for people who watch a lot of movies and can never be bothered to write a proper review right after.

The idea is simple: you just tell Claude (through Claude Desktop) something like "watched Fargo tonight, the dialogue was great but it dragged in the middle", and it turns that into an actual review, saves it with a rating, pulls the director/genre/year from TMDB automatically, and can spit out Letterboxd-ready text whenever you want it. It also remembers your whole watch history, so you can ask it things like "what have I watched by the Coen brothers" or "what should I watch next based on what I've been into lately."

This is a personal tool I built mainly to learn the MCP protocol by actually building something with it, not to ship a polished product. It works and I use it, but treat it like a working prototype, not battle-tested software.

What it actually does

1. You write a rough note about a movie you watched, in your own words, whatever comes to mind.
2. Claude (the one you're already chatting with in Claude Desktop) turns that into a polished review and asks you for a rating.
3. The server looks the movie up on TMDB, grabs the director/genres/year, and stores everything in a local SQLite database.
4. Later, you can ask for your watch history, stats on directors/genres you've been watching a lot, or recommendations based on your habits.
5. When you're ready to log it on Letterboxd, ask for the formatted text and paste it in yourself.

No accounts, no cloud database, no automatic posting anywhere. It's just you, Claude, and a .sqlite3 file on your machine.

Tools

Tool	What it does
search_movie	Searches TMDB by title, returns candidates so Claude can ask "which one did you mean?" if there are several.
log_movie_note	Saves a movie + your raw note + rating (0.5-5 stars, Letterboxd style). Fetches director/genres/year from TMDB the first time a movie shows up.
get_watch_history	Lists what you've logged, filterable by director, genre, or date range.
get_director_stats	How many times you've watched each director, average rating, which titles.
get_recommendations	Returns raw data only - your most-watched director/genre plus movies of theirs you haven't logged yet. No opinions baked in, that's Claude's job.
generate_letterboxd_text	Saves the polished review text and hands back a plain, copy-paste-ready version (no title/year/rating, Letterboxd shows those itself).

Setup

1. Get a TMDB API key

Free, just needs an account: https://www.themoviedb.org/settings/api

2. Install

This is published on PyPI, so the easiest way to run it is with uv - no clone, no venv to manage:

uvx letterbox-buddy

If you'd rather work from source (e.g. to poke at the code), clone it instead:

git clone https://github.com/alpondr/letterbox-buddy-mcp.git
cd letterbox-buddy-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

3. Add your API key

If you're running from source, copy the template and fill it in:

cp .env.example .env

Then open .env and paste your TMDB key in.

If you're running via uvx, there's no project folder for a .env file to live in, so set the key directly in the Claude Desktop config's env block instead (see step 5).

4. Set up the database (optional, happens automatically anyway)

The server creates the SQLite database on first run, at ~/.local/share/letterbox-buddy/db.sqlite3 by default. Want it somewhere else? Set LETTERBOX_DB_PATH in your .env.

If you want to run the migration manually for whatever reason:

python -m letterbox_buddy.db.migrate

5. Connect it to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "letterbox-buddy": {
      "command": "uvx",
      "args": ["letterbox-buddy"],
      "env": {
        "TMDB_API_KEY": "your_tmdb_api_key_here"
      }
    }
  }
}

(If you installed from source instead, point command at your venv's Python, use "args": ["-m", "letterbox_buddy.server"], and you can drop the env block since .env will be picked up from the project folder.)

Restart Claude Desktop (fully quit, not just close the window) and you should see the tools show up.

Notes on design decisions

A few choices here look "wrong" if you're used to bigger projects, so here's the reasoning behind them.

Why SQLite and no auth. Single machine, single user, nothing to authenticate against - Postgres and JWT would just be unused infrastructure here.

Why no separate LLM API. Claude is already right there doing the conversation, so a second LLM would just duplicate work for no reason. The server stays dumb on purpose - fetch/store/return data, all the thinking happens in the chat.

Why Letterboxd posting is copy-paste only. There's no public API for posting on someone's behalf, and I'd rather the last step stay a deliberate human action anyway.

Why "letterbox" not "letterboxd". Not affiliated with Letterboxd, didn't want the name to imply a partnership that doesn't exist.

Known limitations / what this isn't

• Error handling is minimal - happy path only.
• No TMDB rate-limit handling or caching.
• Single machine, no sync between devices.
• No automated tests, everything checked manually.
• Single-user only, no accounts.
• Early on PyPI (v0.1.0), schema may still change between versions.