TMDB MCP Server

A Model Context Protocol (MCP) server that provides integration with The Movie Database (TMDB) API for accessing movie, TV show, and person information. This server allows AI assistants to search for movies and TV shows, get detailed information, discover trending content, and explore cast and crew details.

Features

• Movie Search: Search for movies by title, keywords, or year
• TV Show Search: Search for TV shows by title, keywords, or first air date year
• Detailed Information: Get comprehensive details about movies, TV shows, and people
• Popular Content: Discover popular movies and TV shows
• Trending Content: Get trending movies and TV shows (daily or weekly)
• People Search: Search for actors, directors, and other industry professionals
• Rich Metadata: Access ratings, overviews, cast, crew, and more

Installation

1. Clone this repository:

   git clone <repository-url>
   cd tmdb-mcp-server
   

2. Install dependencies:

   npm install
   

3. Set up environment variables:

   cp .env.example .env
   

4. Edit the .env file with your TMDB configuration:

   PORT=12010
   TMDB_API_KEY=your-tmdb-api-key-here
   TMDB_BASE_URL=https://api.themoviedb.org/3
   

5. Get your TMDB API key:

   • Visit TMDB API
   • Create an account if you don't have one
   • Request an API key
   • Add the API key to your .env file

Usage

Development

npm run dev

Production

npm run build
npm start

Environment Variables

• PORT: The port the MCP server will listen on (default: 12010)
• TMDB_API_KEY: Your TMDB API key (required)
• TMDB_BASE_URL: The TMDB API base URL (default: https://api.themoviedb.org/3)

Available Tools

Movie Tools

• searchMovies: Search for movies by title or keywords
• getMovieDetails: Get detailed information about a specific movie
• getPopularMovies: Get a list of popular movies
• getTrendingMovies: Get trending movies (daily or weekly)

TV Show Tools

• searchTVShows: Search for TV shows by title or keywords
• getTVShowDetails: Get detailed information about a specific TV show
• getPopularTVShows: Get a list of popular TV shows
• getTrendingTVShows: Get trending TV shows (daily or weekly)

People Tools

• searchPeople: Search for people (actors, directors, etc.) by name
• getPersonDetails: Get detailed information about a person

API Endpoints

MCP Endpoint

The main MCP endpoint is available at:

POST http://localhost:12011/mcp

Health Check

GET http://localhost:12010/health

Integration with AI Assistants

This server implements the Model Context Protocol (MCP) and can be integrated with compatible AI assistants. The server supports both standard MCP protocol and legacy tool discovery for backward compatibility.

Example MCP Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "searchMovies",
    "arguments": {
      "query": "The Matrix",
      "year": 1999
    }
  },
  "id": 1
}

Example Response

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"page\": 1,\n  \"total_pages\": 1,\n  \"total_results\": 1,\n  \"results\": [\n    {\n      \"id\": 603,\n      \"title\": \"The Matrix\",\n      \"release_date\": \"1999-03-30\",\n      \"overview\": \"Set in the 22nd century...\",\n      \"vote_average\": 8.2,\n      \"vote_count\": 23000,\n      \"poster_path\": \"https://image.tmdb.org/t/p/w500/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg\",\n      \"backdrop_path\": \"https://image.tmdb.org/t/p/w1280/fNG7i7RqMErkcqhohV2a6cV1Ehy.jpg\",\n      \"genre_ids\": [28, 878],\n      \"popularity\": 85.965\n    }\n  ]\n}"
      }
    ]
  },
  "id": 1
}

Docker Support

A Dockerfile is included for containerized deployment:

docker build -t tmdb-mcp-server .
docker run -p 12010:12010 --env-file .env tmdb-mcp-server

Error Handling

The server includes comprehensive error handling for:

• Invalid TMDB API responses
• Network connectivity issues
• Missing or invalid parameters
• Rate limiting (TMDB API limits)

Rate Limiting

Please be aware of TMDB API rate limits:

• 40 requests every 10 seconds
• Respect the API terms of service

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the ISC License.

Acknowledgments

• The Movie Database (TMDB) for providing the comprehensive movie and TV database API
• Model Context Protocol for the integration standard