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 v4 request_token, redirects the user to TMDB's approval page, and exchanges the approved token for a v4 access_token on /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 — your TMDB_APP_TOKEN secret is missing or invalid. Reset it with bunx 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.