TMDB Model Context Protocol (MCP) Server

A robust Model Context Protocol (MCP) server that seamlessly wraps The Movie Database (TMDB) API. This server enables Large Language Models (LLMs) and MCP-compatible clients (like Claude Desktop) to invoke specialized tools for exploring movie databases, fetching detailed cinematic data, and dynamically retrieving tailored film recommendations.

🌟 Key Features

This server currently exposes four native MCP tools:

• search_movies: Search for movies by title to retrieve a matching list of films alongside their TMDB IDs, release dates, and overviews.
• get_movie_details: Fetch comprehensive information about a specific movie, including its cast, runtime, tagline, average rating, and genres.
• get_popular_movies: Retrieve dynamically paging lists of the current most popular movies globally.
• get_movie_recommendations: Retrieve five intelligently tailored movie recommendations based on a previously selected movie ID.

🛠 Resilience & Architecture

• Graceful Rate Limiting: Properly traps HTTP 429 Too Many Requests when TMDB rate limits are exceeded, presenting clean contextual errors back to the caller instead of crashing.
• Strict STDIO Transport: Ensures no arbitrary stdout pollution occurs so that the standard input/output streams needed for the MCP binary protocol remain pristine.
• Authentication Protected: Built to enforce API keys implicitly via environment variables, safeguarding your private API credentials from being logged payload contents.
• Mock Demo Mode: Built-in mock testing so you can evaluate the agent capabilities locally before you register for an official API token.

---

🚀 Getting Started

Prerequisites

1. Python 3.10 or higher.
2. A free TMDB API Read Access Token.
   • You can get one by signing up for a TMDB account and generating an API token under the Settings > API section.

Installation

1. Clone this repository directly to your machine:

git clone https://github.com/your-username/building-a-custom-mcp.git
cd building-a-custom-mcp

2. Install the required Python dependencies:

pip install -r requirements.txt

(Note: The environment relies on the official mcp SDK and httpx to facilitate robust asynchronous API requests.)

---

🎮 Running the Demo Script

We included a programmatic client script (demo.py) that boots up an isolated MCP session natively and runs test calls against all of the created tools.

To run the live demo with your API key:

# macOS/Linux
export TMDB_API_KEY="your_jwt_token_here"
python demo.py

# Windows Command Prompt
set TMDB_API_KEY=your_jwt_token_here
python demo.py

# Windows PowerShell
$env:TMDB_API_KEY="your_jwt_token_here"
python demo.py

Mock Testing

If you don't have a TMDB key on hand but want to see the exact structural output, you can run the application in "Mock Demo Mode":

# Windows
set TMDB_API_KEY=demo
python demo.py

---

🧩 Integrating with Claude Desktop

To run this server permanently inside Claude Desktop, simply inject this application into your Claude MCP configuration file.

1. Locate your Claude Desktop configuration file:

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

2. Add a new server definition to the mcpServers object. Provide the absolute path to your server.py script and your TMDB token:

{
  "mcpServers": {
    "tmdb": {
      "command": "python",
      "args": [
        "C:\\absolute\\path\\to\\building-a-custom-mcp\\server\\server.py"
      ],
      "env": {
        "TMDB_API_KEY": "YOUR_TMDB_READ_ACCESS_TOKEN_HERE"
      }
    }
  }
}

Note: For Windows paths, ensure backward slashes are explicitly escaped (e.g., C:\\Users\\...).

---

🤝 Contributing

Feel free to open Issues or submit Pull Requests for expansions—such as adding tools for fetching TV shows, actor portfolios, or user reviews!