📌Overview

Purpose: To provide a seamless integration with The Movie Database (TMDB) API for accessing movie information, search functionalities, and personalized recommendations.

Overview: The TMDB MCP Server offers a powerful backend service that leverages the TMDB API, allowing users to retrieve comprehensive movie data, search capabilities, and trending movie insights. Designed for ease of use, the server supports various functionalities that enhance the movie discovery experience.

Key Features:

search_movies: Allows users to search for movies using titles or keywords, returning a list of relevant movies with essential details like titles, release years, and ratings.
get_recommendations: Provides tailored movie recommendations based on a specific movie ID, helping users discover similar content.
get_trending: Fetches the top trending movies for a specified time frame (daily or weekly), keeping users updated on popular trends.
Movies Resource: Accesses detailed information about movies including title, release date, rating, overview, genres, cast, and more, all returned in a convenient JSON format.

TMDB MCP Server

This MCP server integrates with The Movie Database (TMDB) API to provide movie information, search capabilities, and recommendations.

Prerequisites

Before installing and running the TMDB MCP server, ensure you have the following:

Required Software

Node.js
- Version 18.0.0 or higher
- Download from Node.js official website
- Verify installation: node --version
npm (Node Package Manager)
- Version 8.0.0 or higher (comes with Node.js)
- Verify installation: npm --version
TypeScript
- Installed as a project dependency or globally: npm install -g typescript
- Verify installation: tsc --version

Required Accounts & API Keys

TMDB Account
- Free account at TMDB
- API key from TMDB dashboard
- API access must be approved by TMDB
Claude Desktop Application
- Latest version installed
- Access to modify configuration files

System Requirements

Operating Systems
- macOS (10.15 or later)
- Linux (modern distributions)
Hardware
- Minimum 4GB RAM
- 1GB free disk space
- Stable internet connection

Development Environment

Recommended:

A code editor with TypeScript support (e.g., VS Code)
Terminal access
Git (for version control)

Features

Tools

search_movies
- Search movies by title or keywords
- Input: query (string)
- Returns: List of movies with titles, release years, IDs, ratings, and overviews
get_recommendations
- Get movie recommendations based on a movie ID
- Input: movieId (string)
- Returns: Top 5 recommended movies with details
get_trending
- Get trending movies for a specified time window
- Input: timeWindow (string): "day" or "week"
- Returns: Top 10 trending movies with details

Resources

The server provides access to TMDB movie information:

Movies (tmdb:///movie/<movie_id>)
- Movie details including:
  - Title and release date
  - Rating and overview
  - Genres
  - Poster URL
  - Cast information (top 5 actors)
  - Director
  - Selected reviews
- Data returned in JSON format

Getting Started

Get a TMDB API key:
- Sign up at TMDB
- Go to your account settings
- Navigate to the API section
- Request an API key for developer use

Clone and set up the project:

git clone [repository-url]
cd mcp-server-tmdb
npm install

Build the server:
```
npm run build
```
Set your environment variable:
```
export TMDB_API_KEY=your_api_key_here
```

Usage with Claude Desktop

Add the following to your app's server configuration file (located at ~/Library/Application Support/Claude/config.json):

{
  "mcpServers": {
    "tmdb": {
      "command": "/full/path/to/dist/index.js",
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace /full/path/to with your project directory path.

Installing via Smithery

To install TMDB Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @Laksh-star/mcp-server-tmdb --client claude

Example Usage

When running with Claude Desktop, you can use commands like:

Search for movies about artificial intelligence
What are the trending movies today?
Show me this week's trending movies
Get movie recommendations based on movie ID 550
Tell me about the movie with ID 550

Error Handling

The server handles errors including:

Invalid API keys
Network errors
Invalid movie IDs
Malformed requests

Errors are returned in a user-friendly format through Claude Desktop.

Development

To watch for changes during development:

npm run watch

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.