Metadata-Version: 2.4
Name: letterbox-buddy
Version: 0.1.1
Summary: An MCP server that turns your rough movie notes into polished reviews and tracks your watch history
Project-URL: Homepage, https://github.com/alpondr/letterbox-buddy-mcp
Project-URL: Repository, https://github.com/alpondr/letterbox-buddy-mcp
Author: alpondr
License-Expression: MIT
License-File: LICENSE
Keywords: claude,letterboxd,mcp,model-context-protocol,movies
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) - no clone, no venv to manage:

```bash
uvx letterbox-buddy
```

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

```bash
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:

```bash
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:

```bash
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):

```json
{
  "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.
