tmdb-mcp
An MCP server for managing your TMDB lists from Claude, Cursor, or any MCP client. Runs on Cloudflare Workers; bridges OAuth 2.1 to TMDB's v4 auth flow so your TMDB token never leaves the worker.
Tools
| Tool | Description |
|---|---|
list_lists | List all lists for the authenticated TMDB account |
get_list | Fetch a list with its items (paginated) |
create_list | Create a new list |
update_list | Rename, change description, or toggle public |
delete_list | Delete a list |
add_items | Add movies/TV shows to a list |
remove_items | Remove items from a list |
search_movie | Search movies by title (returns ids usable as media_id) |
search_tv | Search TV shows by title |
Architecture
[MCP client] ──OAuth 2.1── [Worker] ──TMDB v4 auth── [themoviedb.org]
│
├── KV (oauth state, opaque tokens)
└── Durable Object (per-session MCP agent)
- The worker presents a standard OAuth 2.1 authorization server to MCP clients.
- On
/authorize, it requests a TMDB v4request_token, redirects the user to TMDB's approval page, and exchanges the approved token for a v4access_tokenon/callback. - The TMDB token is stored only in the per-session props object; clients receive an opaque bearer minted by @cloudflare/workers-oauth-provider.
- All TMDB API calls happen server-side.
Prerequisites
- A Cloudflare account with Workers enabled
- A TMDB account with a v4 API Read Access Token from Settings → API
- Bun
Setup
git clone https://github.com/dendotai/tmdb-mcp.git
cd tmdb-mcp
bun install
Create your own KV namespace and replace the id in wrangler.jsonc:
bunx wrangler kv namespace create OAUTH_KV
Set the TMDB application token as a Worker secret:
bunx wrangler secret put TMDB_APP_TOKEN
# paste your v4 API Read Access Token
Deploy:
bun run deploy
For local development, copy .dev.vars.example to .dev.vars, fill in the token, then:
bun run dev
Connect
Replace https://your-worker.your-subdomain.workers.dev below with your deployed URL.
Claude Code
claude mcp add --transport http tmdb https://your-worker.your-subdomain.workers.dev/mcp
You'll be prompted to complete the OAuth flow in your browser on first use.
Cursor
Settings → MCP → Add new MCP server, paste the URL ending in /mcp.
claude.ai (web)
Settings → Connectors → Add custom connector → paste the /mcp URL.
MCP Inspector
bun run inspector
Then point it at https://your-worker.your-subdomain.workers.dev/mcp (Streamable HTTP transport).
Troubleshooting
- Stream the live worker log:
bun run tail TMDB request_token failed— yourTMDB_APP_TOKENsecret is missing or invalid. Reset it withbunx wrangler secret put TMDB_APP_TOKEN.Authorization session expired or unknown— the OAuth round-trip took longer than 10 minutes, or the user opened the approval link in a different browser session. Restart the connector.- claude.ai web won't finish the connector dance — see the regression note above; verify the server with Claude Code or MCP Inspector.
License
MIT — see LICENSE.