TMDB MCP Server

A Model Context Protocol (MCP) server that provides Claude and other MCP clients access to The Movie Database (TMDB) API.

Features

• Search movies by title
• Get detailed movie information
• Discover trending movies
• Search actors and directors
• Get person details and filmography
• Get movie recommendations
• Advanced movie discovery with filters

Dual Mode Support

This server works in two modes:

• Local (stdio): For Claude Desktop and local MCP clients
• Remote (HTTP): For claude.ai web and remote integrations

Prerequisites

• Go 1.25 or later
• TMDB API key (Get one here)

Installation

# Clone the repository
git clone https://github.com/stormino/tmdb-mcp-server.git
cd tmdb-mcp-server

# Install dependencies
go mod tidy

# Build the server
go build -o tmdb-mcp-server

Configuration

Set your TMDB API key as an environment variable:

export TMDB_API_KEY=your_api_key_here

Usage

Local Mode (Claude Desktop)

1. Build the server (see Installation above)

2. Configure Claude Desktop by editing the config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add this configuration:

{
  "mcpServers": {
    "tmdb": {
      "command": "/absolute/path/to/tmdb-mcp-server",
      "args": ["--mode", "stdio"],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

4. Restart Claude Desktop

5. Ask Claude things like:

   • "Search for movies directed by Christopher Nolan"
   • "What are the trending movies this week?"
   • "Give me details about the movie Inception"

Remote Mode (HTTP Server)

Run the server in HTTP mode:

./tmdb-mcp-server --mode http --port 8080
# Or use make:
make run-http

Testing HTTP Mode Locally

Option 1: MCP Inspector (Recommended)

# Terminal 1: Start server
make run-http

# Terminal 2: Open MCP Inspector
make inspector
# Or: npx @modelcontextprotocol/inspector

Then connect to http://localhost:8080 in the inspector UI at http://localhost:5173

Option 2: cURL

# Test with curl (in another terminal)
make test-http

Option 3: Connect from claude.ai

1. Expose your local server (e.g., using ngrok: ngrok http 8080)
2. Go to claude.ai → Settings → Connectors
3. Click "Add custom connector"
4. Enter your server URL: https://your-ngrok-url.ngrok.io

For detailed testing instructions, see TEST_HTTP_MODE.md

Command Line Options

./tmdb-mcp-server [options]

Options:
  --mode string
        Transport mode: stdio or http (default "stdio")
        Can also be set via MCP_MODE environment variable
  
  --port string
        HTTP port, only used in http mode (default "8080")
        Can also be set via HTTP_PORT environment variable

Available Tools

Example Queries

• "Find movies similar to Interstellar"
• "Who directed The Dark Knight and what are their other movies?"
• "What are the top-rated sci-fi movies from 2023?"
• "Show me trending movies this week"
• "Search for Tom Hanks and list his most popular movies"

Following, a bunch of very complex prompts to test and explore the MCP server capabilities.

Multi-Tool Chain Prompts

• Deep Filmma

... View full README on GitHub