Letterboxd MCP
Provides read-only access to public Letterboxd profile and diary data, including cached retrieval of users' public activity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Letterboxd MCP show my recent Letterboxd diary entries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Letterboxd MCP
A local-first, read-only MCP server for public Letterboxd profile, diary, and watched-film data. It uses FastMCP over stdio, fetches public pages with requests, parses them with BeautifulSoup, and keeps a local SQLite cache.
Requirements
Python 3.12 or newer
Related MCP server: substack-saved-mcp
Install and run
Install the project and its development dependencies:
uv sync --devStart the stdio MCP server from the repository root:
uv run letterboxd-mcpAn MCP client should launch that command as a stdio server. For example, from outside the repository, configure the equivalent of:
{
"mcpServers": {
"letterboxd": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/letterboxd_mcp",
"run",
"letterboxd-mcp"
]
}
}
}Replace the example path with this repository's absolute path.
Tools
The server exposes exactly three read-only tools:
get_profile(username: str, refresh: bool = false)returns normalized public profile details.get_diary(username: str, limit: int = 50, refresh: bool = false)returns up tolimitnormalized diary entries, newest first.get_films(username: str, limit: int = 10, offset: int = 0, refresh: bool = false)returns a page of unique watched titles ordered by newest added and enriched with directors, genres, top-ten cast, runtime, synopsis, aggregate rating, nested diary viewings, and the profile's latest public review.
Example tool arguments:
{"username": "dave"}{"username": "dave", "limit": 25, "refresh": true}{"username": "dave", "limit": 10, "offset": 20}Usernames may contain letters, numbers, underscores, and hyphens. Diary limits must be positive. Watched-film limits must be between 1 and 20, and offsets must be non-negative.
Cache and configuration
By default, data is stored in server.db in the server's working directory. Profiles remain fresh for 30 minutes, profile collections/reviews for 10 minutes, and generic film details for 24 hours. Fresh cached data is returned without an HTTP request; refresh: true always requests current public data. get_films fully synchronizes the public watched collection and diary when stale, but only enriches its requested 10–20 title window.
Configuration is optional and uses LETTERBOXD_MCP_ environment variables. The most useful settings are:
LETTERBOXD_MCP_DATABASE_PATHLETTERBOXD_MCP_PROFILE_TTL_SECONDSLETTERBOXD_MCP_DIARY_TTL_SECONDSLETTERBOXD_MCP_CONNECT_TIMEOUT_SECONDSLETTERBOXD_MCP_READ_TIMEOUT_SECONDSLETTERBOXD_MCP_MAX_RETRIESLETTERBOXD_MCP_USER_AGENT
All TTL and timeout values must be positive. MAX_RETRIES may be zero.
Development
Run the offline test suite and build the distributions:
uv run pytest
uv buildThe implementation keeps MCP tools, service/cache decisions, HTTP behavior, parsers, models, and SQLite repositories in separate layers.
Limitations
This MVP only reads public profile, diary, watched-film, film-detail, and profile-review pages. It does not return community reviews, log in, access private data, write to Letterboxd, bypass challenge pages or CAPTCHAs, or use browser automation. Large profiles can require many public page requests during the first full collection/diary synchronization. Letterboxd markup changes or anti-bot challenges can surface as structured fetch or parse errors.
See LETTERBOXD_MCP_SPEC.md for the product specification and .codex/plan/implementation.md for the implementation ledger.
Available Tools
3 toolsget_diaryGet DiaryBRead-onlyIdempotent
Return normalized public diary entries for a Letterboxd user.
Inputs: username (required), limit, refresh. Returns: result
get_filmsGet FilmsBRead-onlyIdempotent
Return enriched public films watched by a Letterboxd user.
Inputs: username (required), limit, offset, refresh. Returns: A bounded page of enriched watched titles.
get_profileGet ProfileARead-onlyIdempotent
Return normalized public profile information for a Letterboxd user.
Inputs: username (required), refresh. Returns: A normalized public Letterboxd profile.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct aspect of a user's Letterboxd data: profile, diary, and films watched. There is no ambiguity about which tool to use for which purpose.
All tool names follow the exact same get_<noun> pattern, making the naming scheme highly predictable and consistent.
Three tools is well-scoped for a server focused on read-only Letterboxd user data. Each tool covers a clear and essential information need without redundancy.
The set covers profile, diary, and watched films, but omits common Letterboxd data such as watchlist, ratings, reviews, or lists. It is a usable core but leaves notable gaps for a full user data surface.
Maintenance
Related MCP Connectors
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Private journal MCP server to search, analyze, and create Dabble Me entries securely via OAuth.
Remote MCP server for full read/write access to a Zotero library
An MCP server for search and retrieval over a local LanceDB database
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceA comprehensive MCP server that enables users to interact with Letterboxd for searching films, viewing member data, and performing actions like rating or reviewing movies. It supports private data access and automated browser actions for managing watchlists, diaries, and custom lists.1-
- AlicenseAqualityBmaintenanceA local MCP server for managing saved Substack posts. Enables offline reading, searching, bookmarking, and unbookmarking of Substack content via CLI or MCP clients.18MIT

seojeom-mcpofficial
AlicenseNot gradedqualityDmaintenanceLocal-first MCP server that binds to a project opened by the Seojeom desktop app and serves its local wiki and graph data over stdio, enabling project-aware reading, searching, and writing of wiki and graph content.6 npmMIT- AlicenseNot gradedqualityFmaintenanceSynchronizes multiple Gmail and Google Workspace accounts into a local SQLite database and exposes search and mailbox operations through a stdio MCP interface.MIT