tmdb-mcp

一个用于从 Claude、Cursor 或任何 MCP 客户端管理您的 TMDB 列表的 MCP 服务器。运行在 Cloudflare Workers 上；将 OAuth 2.1 桥接到 TMDB 的 v4 认证流程，因此您的 TMDB 令牌永远不会离开 worker。

工具

Related MCP server: Remote MCP Server with Bearer Auth

架构

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

• 该 worker 向 MCP 客户端提供标准的 OAuth 2.1 授权服务器。

• 在 /authorize 端点，它请求一个 TMDB v4 request_token，将用户重定向到 TMDB 的批准页面，并在 /callback 端点将批准后的令牌交换为 v4 access_token。

• TMDB 令牌仅存储在每个会话的 props 对象中；客户端接收由 @cloudflare/workers-oauth-provider 生成的不透明持有者令牌 (bearer token)。

• 所有 TMDB API 调用均在服务器端进行。

先决条件

• 一个启用了 Workers 的 Cloudflare 账户

• 一个拥有 v4 API 读取访问令牌的 TMDB 账户，可在 设置 → API 中获取

• Bun

设置

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

创建您自己的 KV 命名空间并替换 wrangler.jsonc 中的 id：

bunx wrangler kv namespace create OAUTH_KV

将 TMDB 应用程序令牌设置为 Worker 密钥：

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

部署：

bun run deploy

对于本地开发，将 .dev.vars.example 复制到 .dev.vars，填入令牌，然后：

bun run dev

连接

将下方的 https://your-worker.your-subdomain.workers.dev 替换为您部署的 URL。

Claude Code

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

首次使用时，系统会提示您在浏览器中完成 OAuth 流程。

Cursor

设置 → MCP → 添加新 MCP 服务器，粘贴以 /mcp 结尾的 URL。

claude.ai (网页版)

设置 → 连接器 → 添加自定义连接器 → 粘贴 /mcp URL。

MCP Inspector

bun run inspector

然后将其指向 https://your-worker.your-subdomain.workers.dev/mcp（可流式传输的 HTTP 传输）。

故障排除

• 流式传输实时 worker 日志： bun run tail

• TMDB request_token failed — 您的 TMDB_APP_TOKEN 密钥缺失或无效。使用 bunx wrangler secret put TMDB_APP_TOKEN 重置它。

• Authorization session expired or unknown — OAuth 往返时间超过了 10 分钟，或者用户在不同的浏览器会话中打开了批准链接。请重启连接器。

• claude.ai 网页版无法完成连接器流程 — 请参阅上方的回归说明；使用 Claude Code 或 MCP Inspector 验证服务器。

许可证

MIT — 参见 LICENSE。