tmdb-mcp

Claude, Cursor 또는 모든 MCP 클라이언트에서 TMDB 목록을 관리하기 위한 MCP 서버입니다. Cloudflare Workers에서 실행되며, OAuth 2.1을 TMDB의 v4 인증 흐름으로 연결하여 TMDB 토큰이 워커를 벗어나지 않도록 합니다.

도구

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)

• 워커는 MCP 클라이언트에 표준 OAuth 2.1 인증 서버를 제공합니다.

• /authorize에서 TMDB v4 request_token을 요청하고, 사용자를 TMDB 승인 페이지로 리디렉션한 후, /callback에서 승인된 토큰을 v4 access_token으로 교환합니다.

• TMDB 토큰은 세션별 props 객체에만 저장되며, 클라이언트는 @cloudflare/workers-oauth-provider에서 발행한 불투명한 베어러 토큰을 받습니다.

• 모든 TMDB API 호출은 서버 측에서 발생합니다.

사전 요구 사항

• Workers가 활성화된 Cloudflare 계정

• 설정 → API에서 v4 API 읽기 액세스 토큰을 가진 TMDB 계정

• 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 애플리케이션 토큰을 워커 시크릿으로 설정하세요:

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 전송)를 가리키도록 하세요.

문제 해결

• 라이브 워커 로그 스트리밍: 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를 참조하세요.