tmdb-mcp

Un servidor MCP para gestionar tus listas de TMDB desde Claude, Cursor o cualquier cliente MCP. Se ejecuta en Cloudflare Workers; conecta OAuth 2.1 con el flujo de autenticación v4 de TMDB para que tu token de TMDB nunca salga del worker.

Herramientas

Related MCP server: Remote MCP Server with Bearer Auth

Arquitectura

[MCP client]  ──OAuth 2.1──  [Worker]  ──TMDB v4 auth──  [themoviedb.org]
                                │
                                ├── KV  (oauth state, opaque tokens)
                                └── Durable Object  (per-session MCP agent)

• El worker presenta un servidor de autorización OAuth 2.1 estándar a los clientes MCP.

• En /authorize, solicita un request_token de TMDB v4, redirige al usuario a la página de aprobación de TMDB e intercambia el token aprobado por un access_token v4 en /callback.

• El token de TMDB se almacena solo en el objeto de propiedades por sesión; los clientes reciben un bearer opaco generado por @cloudflare/workers-oauth-provider.

• Todas las llamadas a la API de TMDB ocurren en el lado del servidor.

Requisitos previos

• Una cuenta de Cloudflare con Workers habilitados

• Una cuenta de TMDB con un API Read Access Token v4 desde Configuración → API

• Bun

Configuración

git clone https://github.com/dendotai/tmdb-mcp.git
cd tmdb-mcp
bun install

Crea tu propio espacio de nombres KV y reemplaza el id en wrangler.jsonc:

bunx wrangler kv namespace create OAUTH_KV

Establece el token de la aplicación TMDB como un secreto del Worker:

bunx wrangler secret put TMDB_APP_TOKEN
# paste your v4 API Read Access Token

Despliega:

bun run deploy

Para el desarrollo local, copia .dev.vars.example a .dev.vars, rellena el token y luego:

bun run dev

Conectar

Reemplaza https://your-worker.your-subdomain.workers.dev a continuación con tu URL desplegada.

Claude Code

claude mcp add --transport http tmdb https://your-worker.your-subdomain.workers.dev/mcp

Se te pedirá completar el flujo OAuth en tu navegador la primera vez que lo uses.

Cursor

Settings → MCP → Add new MCP server, pega la URL que termina en /mcp.

claude.ai (web)

Settings → Connectors → Add custom connector → pega la URL /mcp.

MCP Inspector

bun run inspector

Luego apúntalo a https://your-worker.your-subdomain.workers.dev/mcp (transporte HTTP transmitible).

Solución de problemas

• Transmitir el registro del worker en vivo: bun run tail

• TMDB request_token failed — tu secreto TMDB_APP_TOKEN falta o no es válido. Restablécelo con bunx wrangler secret put TMDB_APP_TOKEN.

• Authorization session expired or unknown — el viaje de ida y vuelta de OAuth tomó más de 10 minutos, o el usuario abrió el enlace de aprobación en una sesión de navegador diferente. Reinicia el conector.

• claude.ai web no termina el proceso del conector — consulta la nota de regresión anterior; verifica el servidor con Claude Code o MCP Inspector.

Licencia

MIT — ver LICENSE.