Letterboxd MCP Server

Origin Note: This project was originally based on Racimy/Letterboxd-MCP. It has since been extensively rewritten and expanded (V3+) to include comprehensive Playwright actions, multi-mode transport (Stdio/SSE), and expanded toolsets.

A Model Context Protocol (MCP) server for Letterboxd. It enables AI models to interact with Letterboxd data and perform account actions like rating films, writing reviews, and managing watchlists.

This server uses Playwright for authenticated account actions and fast HTML scraping for read endpoints.

Features

• Rich Film Metadata: Fetch posters, cast, runtime, genres, and synopses.
• Search: Comprehensive search for films, members, lists, and reviews.
• Member Insights: Get profile summaries, stats, watchlists, diary entries, and ratings.
• Account Management:
  • Rate films (0.5 to 5 stars).
  • Toggle "Watched", "Watchlist", and "Like" status.
  • Write and update reviews (supports ratings, spoilers, and rewatch flags).
  • Create and manage lists.
• me Shortcut: Use "me" as a username to target your authenticated account.
• Automatic Pagination: Fetches all pages by default or supports manual cursor-based navigation.

Installation

Prerequisites

• Node.js (v18+)
• npm

Setup

1. Clone the repository:

   git clone https://github.com/yourusername/Letterboxd-MCP.git
   cd Letterboxd-MCP
   

2. Install dependencies:

   npm install
   

   Note: This will also download Chromium for Playwright.

3. Create a .env file (see Configuration):

   cp .env.example .env
   

Configuration

The server is configured via environment variables. Create a .env file in the root directory:

# Required for account actions & private data
LETTERBOXD_USERNAME=your_username
LETTERBOXD_PASSWORD=your_password

# Optional
PORT=3000
MCP_API_KEY=your_optional_secret_key
LETTERBOXD_LOGIN_FOR_READS=true # Set to false to avoid logging in for public data

Usage

Stdio Mode (Recommended for local MCP clients)

To run the server in Stdio mode for local clients like Claude Desktop:

node index.js --mode=stdio

SSE Mode (For remote integrations)

To run the server in SSE (Server-Sent Events) mode:

npm start

Integration with AI Agents

For detailed instructions on how to configure an AI agent (like Claude or Gemini) to use this server effectively, including specialized workflows like natural language review posting, see the Agent Instructions & Example Guide.

Integration with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "letterboxd": {
      "command": "node",
      "args": ["/absolute/path/to/Letterboxd-MCP/index.js", "--mode=stdio"],
      "env": {
        "LETTERBOXD_USERNAME": "your_username",
        "LETTERBOXD_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

Read Tools

• search: Search Letterboxd (films, lists, members, reviews).
• get_film: Get detailed metadata for a film.
• get_member: Get profile and stats for a member.
• get_member_watchlist: List films in a member's watchlist.
• get_member_diary: List a member's diary entries.
• get_member_films: List films a member has watched.
• get_member_ratings: List films rated by a member.
• get_member_reviews: List reviews written by a member.
• get_member_pinned: Get a member's favorite/pinned films.
• get_member_lists: List lists created by a member.
• get_list: Get entries and metadata for a specific list.
• get_review: Get full review details.
• get_current_user: Check authentication status.

Write Tools (Requires Authentication)

• rate_film: Set a star rating.
• add_to_watched: Mark a film as watched/unwatched.
• add_to_watchlist: Add/remove a film from your watchlist.
• toggle_like: Like/unlike a film.
• write_review: Write or update a review.
• write_review_by_title: Search by title and write a review.
• add_to_list: Add a film to an existing list.
• create_list: Create a new list.

Development & Testing

Running Tests

• Read-only tests: npm run test:read
• Mutating tests (Requires live credentials): RUN_MUTATING_TESTS=true npm run test:mutating
• All tests: npm run test:all

Credits

This project was originally based on Racimy/Letterboxd-MCP. It has since been extensively rewritten and expanded (V3+) to include comprehensive Playwright actions, multi-mode transport (Stdio/SSE), and expanded toolsets.

Security Warning

This server uses Playwright to automate your Letterboxd account. Never share your .env file or commit it to version control. Always use a strong MCP_API_KEY if running in SSE mode over the internet.

License

ISC