Skip to main content

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.

Metadata

Release files for letterbox-buddy 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for letterbox-buddy 0.1.1
File Size Uploaded Provenance Actions
letterbox_buddy-0.1.1.tar.gz 9.6 kB Without provenance Details for letterbox_buddy-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for letterbox-buddy 0.1.1
File Interpreter ABI Platform Actions
letterbox_buddy-0.1.1-py3-none-any.whl Python 3 none any Details for letterbox_buddy-0.1.1-py3-none-any.whl

Total release size: 24.9 kB

Release files / letterbox_buddy-0.1.1.tar.gz

Download URL letterbox_buddy-0.1.1.tar.gz
Size 9.6 kB
Tags Source
SHA-256 checksum
How to use checksums
02e94f4a32abc4719983a75459f230c76de72cd7c0e6a45bf65f2e1ba8338a96
BLAKE2b-256 checksum
How to use checksums
0cb8e29e1d02d23b66ea63b7465e9397487bc7c4f6ae4dde2403ea47fd91919a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Release files / letterbox_buddy-0.1.1-py3-none-any.whl

Download URL letterbox_buddy-0.1.1-py3-none-any.whl
Size 15.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a5ad739136d11ff869f82d068d988f4d30c25f3b271834183624090ba80494ee
BLAKE2b-256 checksum
How to use checksums
ab79b917123420fb17ca2d890f2f93a3a36f9bae512e45794b9b85bad47c793a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Security for letterbox-buddy 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page