io.github.cyanheads/tmdb-mcp-server

@cyanheads/tmdb-mcp-server

Search movies, TV, and people on The Movie Database (TMDB) — credits, ratings, trailers, images, recommendations, and region-aware streaming availability via MCP. STDIO or Streamable HTTP.

8 Tools • 3 Resources

Overview

Movie and TV metadata powered by The Movie Database (TMDB). Search titles and people by name, pull full credits and filmographies, discover titles by filtered criteria, track trending content, and check where to stream in your region.

Tools

Resources

Capability reference

tmdb_search_titles tool

• multi mode (default) mixes movies, shows, and people, tagged with media_type; movie, tv, or person restrict to one type
• Optional year (movie/tv modes), language, include_adult, and page; empty results return normally with recovery guidance
• Each result carries id, media_type, title/name, release_year, overview, vote_average, genre_names, and a poster or profile URL

tmdb_get_movie tool

• Returns credits, videos, recommendations, similar, keywords, external ids, and release dates in one call; trim the append array (e.g. ["credits"]) to shrink the payload
• Includes US certification, top-billed cast, key crew, and YouTube trailers with watch URLs
• No streaming availability; use tmdb_get_watch_providers

tmdb_get_show tool

• Same append options as tmdb_get_movie, with content_ratings (US TV rating) in place of release_dates
• Adds season summaries, creators, networks, and the last/next episode to air
• Pass a season_number from seasons[] to tmdb_get_season for episodes

tmdb_get_season tool

• Per-episode names, air dates, runtimes, vote averages, still URLs, and guest stars
• Also returns the season's regular cast
• series_id is echoed from the input; season 0 is "Specials"

tmdb_get_person tool

• Biography, vital dates, place of birth, known-for department, aliases, gender, and external ids (IMDb, Wikidata, social handles)
• combined_credits split into cast_credits and crew_credits, newest first; credits_page (default 1) returns up to 50 of each, with full totals on every page
• Follow next_credits_page for more; pages past the end return empty lists

tmdb_discover_titles tool

• Filter by with_genres/without_genres, year or a release_date_gte/lte window, vote_average range, vote_count_gte, with_cast/with_crew (movie), with_networks (tv), with_watch_providers + watch_region, with_original_language, and runtime range
• Sort by popularity, revenue, vote average, vote count, or release date; pair vote_average.desc with vote_count_gte (~100–1000) to keep low-vote titles out of the top
• Filters that don't apply to the media type produce a notice; with_watch_providers without watch_region returns region_required

tmdb_get_trending tool

• media_type: all (default) mixes movies, shows, and people; or restrict to one type
• time_window: day or week (default)
• Up to 20 results per page, with page for more; empty results return normally with recovery guidance

tmdb_get_watch_providers tool

• Returns flatrate, rent, buy, ads, and free provider lists with logo URLs, plus the TMDB JustWatch link
• watch_region (ISO 3166-1 alpha-2) is required; the response always states the region
• An empty result means not streamable in that region; provider ids feed with_watch_providers in tmdb_discover_titles

tmdb://movie/{movie_id} resource

• Same record as tmdb_get_movie — application/json
• movie_id comes from tmdb_search_titles or tmdb_discover_titles
• Typed movie_not_found error when TMDB returns 404 for the id

tmdb://tv/{series_id} resource

• Same record as tmdb_get_show — application/json
• series_id comes from tmdb_search_titles or tmdb_discover_titles
• Typed show_not_found error when TMDB returns 404 for the id

tmdb://person/{person_id} resource

• Person detail with the first 50 cast and 50 crew credits and full totals — application/json; use tmdb_get_person for further pages
• person_id comes from tmdb_search_titles (mode "person")
• Typed person_not_found error when TMDB returns 404 for the id

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

TMDB-specific:

• Typed client for the TMDB v3 REST API, authenticated with a v4 Read Access Token
• Image paths resolved to full image URLs; missing paths omit the field
• Genre ids resolved to genre names, so list results are readable without an extra call
• Detail tools return credits, videos, recommendations, keywords, and external ids in one request
• Region-aware streaming availability backed by JustWatch; region is always an explicit input

Agent-friendly output:

• TMDB attribution on every response in enrichment.attribution
• List responses carry total counts, page/total-pages, and a notice of the filters actually applied
• Empty results return normally with recovery guidance, not as errors
• Watch-provider results always state the region; capped filmographies disclose their full totals

Getting started

A TMDB API Read Access Token is required. Create a free TMDB account, then copy the API Read Access Token (a v4 JWT) from your API settings — this server authenticates v3 endpoints with Authorization: Bearer <token>, not the legacy ?api_key= query parameter.

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/tmdb-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TMDB_API_KEY": "your-tmdb-read-access-token"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/tmdb-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TMDB_API_KEY": "your-tmdb-read-access-token"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "TMDB_API_KEY=your-tmdb-read-access-token",
        "ghcr.io/cyanheads/tmdb-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TMDB_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A TMDB API Read Access Token (v4 JWT) — free from your TMDB API settings.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/tmdb-mcp-server.git

1. Navigate into the directory:

cd tmdb-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set TMDB_API_KEY

Configuration

All configuration is validated at startup via Zod schemas. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t tmdb-mcp-server .
docker run --rm -e TMDB_API_KEY=your-token -p 3010:3010 tmdb-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/tmdb-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See AGENTS.md (or CLAUDE.md, the same content) for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB. Streaming availability data is provided by JustWatch via TMDB and is region-specific.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.