TMDB MCP Server

A production-ready Model Context Protocol (MCP) server that integrates with The Movie Database (TMDB) API, designed to run on Cloudflare Workers using Hono.js framework.

Features

• 34 MCP Tools for comprehensive TMDB API access
• Dual Transport Support: SSE (legacy) and Streamable HTTP (new standard)
• Cloudflare Cache integration for improved performance
• Robust Error Handling with graceful error messages
• Type-Safe with full TypeScript support
• Rate Limit Aware with proper error responses

Available Tools

Search & Discovery

Tool	Description
search_movies	Search for movies by title with optional year filter
search_tv_shows	Search for TV shows by name
search_person	Search for actors, directors, and crew
discover_movies	Advanced movie discovery with filters
discover_tv	Advanced TV show discovery with filters
get_trending	Get trending movies, TV shows, or people

Movie Details

Tool	Description
get_movie_details	Get comprehensive movie details including cast & crew
get_movie_recommendations	Get movie recommendations based on a movie
get_similar_movies	Get movies similar to a specific movie
get_movie_videos	Get all videos (trailers, teasers, clips) for a movie
get_movie_images	Get all images (posters, backdrops, logos) for a movie
get_movie_reviews	Get user reviews for a movie

TV Show Details

Tool	Description
get_tv_details	Get TV show details including seasons and episodes
get_tv_recommendations	Get TV show recommendations based on a show
get_similar_tv	Get TV shows similar to a specific show
get_tv_videos	Get all videos for a TV show
get_tv_images	Get all images for a TV show
get_tv_reviews	Get user reviews for a TV show
get_season_details	Get detailed information about a TV show season
get_episode_details	Get detailed information about a TV show episode

Person Details

Tool	Description
get_person_details	Get person biography and filmography
get_person_images	Get all profile images for a person

Lists & Charts

Tool	Description
get_now_playing	Get movies currently playing in theaters
get_upcoming	Get movies being released in the next 2 weeks
get_popular_movies	Get current popular movies
get_top_rated_movies	Get top rated movies of all time
get_latest_movie	Get the most recently added movie
get_airing_today	Get TV shows airing today
get_on_the_air	Get TV shows currently on the air
get_popular_tv	Get current popular TV shows
get_top_rated_tv	Get top rated TV shows of all time
get_latest_tv	Get the most recently added TV show

Reference Data

Tool	Description
get_movie_certifications	Get movie certifications by country
get_tv_certifications	Get TV show certifications by country

Prerequisites

• Node.js 18+
• npm or yarn
• TMDB API Key (Read Access Token)
• Cloudflare account (for deployment)

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Create a .dev.vars file for local development:

cp .dev.vars.example .dev.vars

Edit .dev.vars and add your TMDB API key:

TMDB_API_KEY=your_tmdb_api_key_here

3. Local Development

Start the development server:

npm run dev

The server will be available at http://localhost:8787

4. Test Endpoints

Offline test suite:

npm test

Live integration tests (require TMDB_API_KEY and outbound access to api.themoviedb.org):

npm run test:endpoints
npm run test:integration

Health Check:

curl http://localhost:8787/health

List Available Tools:

curl http://localhost:8787/tools

SSE Connection (for MCP clients):

curl -N http://localhost:8787/sse

Deployment

Deploy to Cloudflare Workers

1. Set the TMDB API key as a secret:

wrangler secret put TMDB_API_KEY

2. Deploy:

npm run deploy

MCP Client Configuration

SSE Transport (Legacy)

Configure your MCP client to connect using SSE:

{
  "mcpServers": {
    "tmdb": {
      "url": "http://localhost:8787/sse",
      "transport": "sse"
    }
  }
}

Streamable HTTP Transport (Recommended)

The newer, more efficient transport protocol:

{
  "mcpServers": {
    "tmdb": {
      "url": "http://localhost:8787/mcp",
      "transport": "streamable-http"
    }
  }
}

For deployed workers:

{
  "mcpServers": {
    "tmdb": {
      "url": "https://tmdb-mcp-server.<your-subdomain>.workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

Available Endpoints

Endpoint	Method	Description
/health	GET	Health check and server info
/tools	GET	List all available tools
/sse	GET	SSE transport connection (legacy)
/message	POST	SSE transport messages (legacy)
/mcp	GET/POST/DELETE	Streamable HTTP transport

Tool Usage Examples

Search Movies

{
  "name": "search_movies",
  "arguments": {
    "query": "The Matrix",
    "year": 1999
  }
}

Get Movie Details

{
  "name": "get_movie_details",
  "arguments": {
    "movie_id": 603
  }
}

Discover Movies

{
  "name": "discover_movies",
  "arguments": {
    "genres": "28,12",
    "min_rating": 7.5,
    "sort_by": "popularity.desc"
  }
}

Get Trending

{
  "name": "get_trending",
  "arguments": {
    "media_type": "movie",
    "time_window": "week"
  }
}

Project Structure

tmdb-mcp/
├── src/
│   ├── index.ts           # Main server entry point
│   └── lib/
│       ├── tmdb-client.ts # TMDB API client with caching
│       └── mcp-tools.ts   # MCP tool definitions
├── package.json
├── wrangler.toml
├── tsconfig.json
└── .dev.vars.example

API Reference

TMDBClient

The TMDBClient class provides a type-safe wrapper around the TMDB API:

• Automatic error handling
• Rate limit detection (429 responses)
• Cloudflare Cache integration
• Image URL transformation

Image URLs

All image paths returned by tools are converted to full URLs using the format:

https://image.tmdb.org/t/p/w500/{path}

Available sizes: w92, w154, w185, w342, w500, w780, original

Error Handling

The server handles various error scenarios:

• TMDB API Errors: Returns descriptive error messages
• Rate Limiting: Returns 429 with retry-after header
• Network Errors: Graceful error messages
• Invalid Input: Zod validation errors

License

MIT