TMDB MCP server

The TMDB MCP Server integrates with The Movie Database (TMDB) API through the Model Context Protocol. This enables AI assistants like Claude to search for movies, retrieve movie details, and generate movie-related content through a structured interface.

Installation

Prerequisites

• Node.js (v16 or later)
• npm or yarn
• TMDB API key

Setup Process

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/your-username/tmdb-mcp.git
   cd tmdb-mcp
   

2. Install dependencies:

   npm install
   

3. Configure your TMDB API key:

   • Create a .env file in the project root
   • Add your API key to this file:

     TMDB_API_KEY=your_api_key_here
     

4. Build the project:

   npm run build
   

5. Start the server:

   npm start
   

Configuring Claude Desktop

1. Open Claude Desktop application
2. Navigate to Settings > Developer tab
3. Click "Edit Config" to open the configuration file
4. Add the following configuration:

   {
     "mcpServers": {
       "tmdb-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/your/tmdb-mcp/build/index.js"]
       }
     }
   }
   

5. Restart Claude Desktop to apply changes

Using the MCP Server

Available Resources

The server provides several types of resources for interacting with movie data:

• Static Resources:

  • tmdb://info - Information about TMDB API
  • tmdb://trending - Currently trending movies

• Resource Templates:

  • tmdb://movie/{id} - Detailed information about a specific movie by ID

Using Prompts

The server supports specialized prompts for movie-related content:

• Movie Reviews: Generate customized movie reviews with specified style and rating

  • Example: "Write a detailed review for Inception with a rating of 9/10"

• Movie Recommendations: Get personalized recommendations based on genres and mood

  • Example: "Recommend sci-fi movies for a thoughtful mood"

Using Tools

Several tools are available for movie exploration:

• Search Movies: Find movies by title or keywords

  • Example: "Search for movies about space exploration"

• Get Trending Movies: Retrieve trending movies for day or week

  • Example: "What are the trending movies today?"

• Get Similar Movies: Find movies similar to a specified movie

  • Example: "Find movies similar to The Matrix"

Example Interactions

You can interact with the server using natural language queries:

• "What is TMDB?"
• "Show me currently trending movies"
• "Get details about movie with ID 550" (retrieves Fight Club)
• "Tell me about the movie with ID 155" (retrieves The Dark Knight)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.