TMDB MCP Server

A Model Context Protocol (MCP) server that provides access to The Movie Database (TMDB) API. This server enables AI assistants like Cursor to search for movies, TV shows, people, get detailed information, trending content, and recommendations.

Features

🔍 Search Tools

• Search Movies: Find movies by title with optional year filtering
• Search TV Shows: Find TV shows by name with optional year filtering
• Search People: Find actors, directors, and other industry professionals
• Multi Search: Universal search across movies, TV shows, and people

📱 Details Tools

• Movie Details: Get comprehensive movie information including cast, crew, budget, revenue
• TV Show Details: Get detailed TV show information including seasons, episodes, networks
• Person Details: Get detailed person information including biography and filmography
• Movie Credits: Get cast and crew information for movies
• TV Show Credits: Get cast and crew information for TV shows

📈 Discovery Tools

• Trending Content: Get trending movies, TV shows, and people (daily/weekly)
• Popular Content: Get most popular movies, TV shows, and people
• Recommendations: Get movie and TV show recommendations based on specific titles
• Similar Content: Find similar movies and TV shows

Prerequisites

• Node.js 18.x or higher
• TMDB API key (free registration at TMDB)

Setup

1. Install Dependencies

   npm install

2. Get TMDB API Key

   • Go to TMDB API
   • Register for a free account
   • Generate an API key

3. Configure Environment

   • Copy .env file and add your API key:

   TMDB_API_KEY=your_actual_api_key_here
   TMDB_BASE_URL=https://api.themoviedb.org/3

4. Build the Project

   npm run build

Usage

Running the Server Directly

npm start

Development Mode

npm run dev

Integration with Cursor

Add this configuration to your Cursor MCP settings:

{
  "mcpServers": {
    "tmdb": {
      "command": "node",
      "args": ["/home/ttpl-lnvl15-0288/Projects/movie-mcp/dist/server.js"],
      "cwd": "/home/ttpl-lnvl15-0288/Projects/movie-mcp"
    }
  }
}

Available Tools

Search Tools

• search_movies(query, year?, page?) - Search for movies
• search_tv_shows(query, year?, page?) - Search for TV shows
• search_people(query, page?) - Search for people
• search_multi(query, page?) - Universal search

Details Tools

• get_movie_details(id) - Get detailed movie information
• get_tv_show_details(id) - Get detailed TV show information
• get_person_details(id) - Get detailed person information
• get_movie_credits(id) - Get movie cast and crew
• get_tv_show_credits(id) - Get TV show cast and crew

Discovery Tools

• get_trending_movies(timeWindow?, page?) - Get trending movies
• get_trending_tv_shows(timeWindow?, page?) - Get trending TV shows
• get_trending_people(timeWindow?, page?) - Get trending people
• get_popular_movies(page?) - Get popular movies
• get_popular_tv_shows(page?) - Get popular TV shows
• get_popular_people(page?) - Get popular people
• get_movie_recommendations(id, page?) - Get movie recommendations
• get_tv_show_recommendations(id, page?) - Get TV show recommendations
• get_similar_movies(id, page?) - Get similar movies
• get_similar_tv_shows(id, page?) - Get similar TV shows

Example Usage

Once connected through Cursor, you can ask questions like:

• "Search for movies about space exploration"
• "Get details about the movie Inception"
• "What are the trending movies this week?"
• "Find movies similar to The Matrix"
• "Who are the most popular actors right now?"
• "Get the cast and crew for Breaking Bad"

Rate Limiting

The server implements TMDB's rate limiting (40 requests per 10 seconds) automatically with proper queuing and retry logic.

Error Handling

• Comprehensive error handling for API failures
• Input validation using Zod schemas
• Graceful handling of network errors and rate limits

Future Expansions

This architecture can be easily adapted for other APIs such as:

• Athena Health: Patient data, appointment scheduling, clinical workflows
• Cerner: EHR integration, clinical decision support, reporting
• Epic MyChart: Patient portal integration, health records access

Development

Project Structure

src/
├── server.ts              # Main MCP server
├── tmdb-client.ts         # TMDB API wrapper
├── types/
│   └── tmdb.ts           # TypeScript type definitions
└── tools/
    ├── search.ts         # Search tools
    ├── details.ts        # Details tools
    └── discovery.ts      # Discovery tools

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Run in development mode with ts-node
• npm start - Start the built server
• npm run clean - Clean build directory

License

MIT License - see LICENSE file for details.

Contributing

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

Support

For issues and questions:

1. Check the TMDB API documentation
2. Verify your API key is valid
3. Check server logs for error messages
4. Ensure Node.js version compatibility