TMDB

What is mcp-server-tmdb?

mcp-server-tmdb is a server designed to extend the functionality of Claude Desktop by integrating with The Movie Database (TMDB) API. It allows users to access movie information, perform searches, and receive recommendations directly through their Claude Desktop application. This project is built with JavaScript and leverages Node.js and npm.

How to use mcp-server-tmdb?

To use mcp-server-tmdb, you need to have Node.js (v18.0.0+), npm (v8.0.0+), and TypeScript installed. You also need a TMDB API key and the Claude Desktop application. The setup involves cloning the repository, installing dependencies, building the server, and setting up an environment variable for your TMDB API key. Integration with Claude Desktop requires modifying its configuration file to include the server. Alternatively, you can install it automatically via Smithery CLI.

Key Features of mcp-server-tmdb

search_movies: Search for movies by title or keywords, returning details like title, release year, ID, rating, and overview.
get_recommendations: Obtain movie recommendations based on a given TMDB movie ID.
get_trending: Retrieve a list of trending movies for a specified time window (day or week).
Movie Details Access: Provides comprehensive movie details including title, release date, rating, overview, genres, poster URL, cast, director, and selected reviews.
Error Handling: Includes robust error handling for invalid API keys, network issues, invalid movie IDs, and malformed requests.

Use Cases of mcp-server-tmdb

Movie Information Retrieval: Quickly get details about any movie.
Movie Discovery: Find new movies through trending lists or recommendations.
Integration with AI Assistants: Enhance AI assistant capabilities (like Claude Desktop) with real-time movie data.
Development: Provides a foundation for building applications that require TMDB integration.

FAQ about mcp-server-tmdb

Q: What are the prerequisites for running mcp-server-tmdb? A: You need Node.js (v18.0.0+), npm (v8.0.0+), TypeScript, a TMDB API key, and the Claude Desktop application.

Q: How do I get a TMDB API key? A: You can sign up at TMDB, go to your account settings, navigate to the API section, and request an API key for developer use.

Q: Can I use this server with other applications besides Claude Desktop? A: While primarily designed for Claude Desktop, the server provides a general API integration with TMDB, so it could potentially be adapted for other applications that can interact with external servers.

Q: How do I handle errors? A: The server includes comprehensive error handling, and error messages are returned in a user-friendly format through Claude Desktop.

Q: Is there a way to install this automatically? A: Yes, you can use the Smithery CLI to install it automatically with npx -y @smithery/cli install @Laksh-star/mcp-server-tmdb --client claude.

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 prerequisites installed and configured:

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
- Will be installed as a project dependency
- Can be installed 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 Requirements
- Minimum 4GB RAM
- 1GB free disk space
- Stable internet connection

Development Environment

For the best development experience, we recommend:

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

Features

Tools

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

Resources

The server provides access to TMDB movie information:

Movies (tmdb:///movie/<movie_id>)
- Comprehensive movie details including:
  - Title and release date
  - Rating and overview
  - Genres
  - Poster URL
  - Cast information (top 5 actors)
  - Director
  - Selected reviews
- All data is 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 up your environment variable:
```
export TMDB_API_KEY=your_api_key_here
```

Usage with Claude Desktop

To integrate this server 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 the actual path to your project directory.

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

Once the server is running with Claude Desktop, you can use commands like:

Search for movies:

"Search for movies about artificial intelligence"

Get trending movies:

"What are the trending movies today?"
"Show me this week's trending movies"

Get movie recommendations:

"Get movie recommendations based on movie ID 550"

Get movie details:
```
"Tell me about the movie with ID 550"
```

Error Handling

The server includes comprehensive error handling for:

Invalid API keys
Network errors
Invalid movie IDs
Malformed requests

Error messages will be 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.

TMDB Overview