wizzy-mcp-tmdb

Standardized MCP server to access and search The Movie Database content for AI clients.

Stars

Forks

Watchers

Issues

wizzy-mcp-tmdb is a Model Context Protocol (MCP) server implemented in JavaScript, designed to provide AI clients with tools to search and retrieve data from The Movie Database (TMDB). It offers standardized endpoints for multi-search, fetching detailed movie or TV information, and retrieving trending content. The server communicates over stdio and can be easily integrated into MCP-compatible clients via configuration. Comprehensive unit and integration tests ensure reliability across typical and edge-case API uses.

Key Features

MCP server implementation for TMDB

Multi-type search functionality across movies, TV shows, and people

Standardized API endpoints for information retrieval

Stdio-based communication for client integration

Tools for fetching trending content and item details

Environment variable configuration with API token support

Simple npm-based installation and usage

Comprehensive unit and integration test coverage

Support for additional TMDB tools and providers

Easy configuration for MCP-compatible environments

Use Cases

Enhancing AI assistants with up-to-date movie and TV information

Integrating movie and TV search capabilities into chat and IDE platforms

Fetching trending multimedia content for recommendation systems

Retrieving detailed actor, movie, and TV show metadata for conversational agents

Building knowledge retrieval layers for entertainment-focused AI solutions

Automating content discovery and information gathering for film/TV workflows

Providing consistent contextual data for creative AI applications

Supporting multi-language and international content discovery scenarios

Testing and validation of AI interactions with standardized entertainment data sources

Streamlining integration with The Movie Database in customizable client environments

README

wizzy-mcp-tmdb

Project Overview and Purpose

The wizzy-mcp-tmdb project is an MCP (Model Context Protocol) server implemented in JavaScript that provides tools to search and retrieve information from The Movie Database (TMDB). It allows AI clients to access movie, TV show, and person data through a standardized protocol.

Key Features

Search Movies: Perform multi-search across movies, TV shows, and people using the search_tmdb tool.
Get Details: Fetch detailed information for specific items using the get_tmdb_details tool.
Trending Content: Retrieve trending content across all media types with the trending_all tool.

Installation

Prerequisites

Node.js version 18 or higher (required for global fetch support)
A TMDB API key (Bearer token) from your admin, used with the TNL TMDB proxy (production-api.tnl.one)

Setup

Clone the repository and navigate to the project directory.
Install dependencies:
bash
```
npm install
```
Set up your TMDB API key as an environment variable:
- On Windows PowerShell:
  powershell
```
$env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
```
- On macOS/Linux:
  bash
```
export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
```

Usage

Starting the MCP Server

To start the server:

bash

npm start

The server communicates over stdio and should be configured in your MCP-compatible client (e.g., IDE or chat client) with the command node mcp-tmdb-server.js and the TMDB_AUTH_TOKEN environment variable.

MCP Integration Examples

Here are code snippets showing how to integrate with the MCP tools:

Search for Movies

javascript

// Example MCP tool call for searching
{
  "method": "tools/call",
  "params": {
    "name": "search_tmdb",
    "arguments": {
      "query": "dune",
      "page": 1,
      "language": "en-US",
      "include_adult": false
    }
  }
}

Get Movie Details

javascript

// Example MCP tool call for getting details
{
  "method": "tools/call",
  "params": {
    "name": "get_tmdb_details",
    "arguments": {
      "type": "movie",
      "id": 438631,
      "append": "credits,images"
    }
  }
}

Get Trending Content

javascript

// Example MCP tool call for trending content
{
  "method": "tools/call",
  "params": {
    "name": "trending_all",
    "arguments": {
      "time_window": "day",
      "page": 1,
      "language": "en-US"
    }
  }
}

MCP Client Integration

Per integrare questo MCP server nel tuo client MCP (come un IDE o un client di chat compatibile), segui questi passi:

Installa il pacchetto npm se necessario:
bash
```
npm install -g wizzy-mcp-tmdb
```

Crea o aggiorna il file mcp.json nel tuo client MCP con la seguente configurazione:

json

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["wizzy-mcp-tmdb"],
      "env": {
        "TMDB_AUTH_TOKEN": "YOUR_TNL_PROXY_BEARER_TOKEN"
      },
      "alwaysAllow": [
        "get_watch_providers",
        "discover_tv",
        "discover_by_provider"
      ]
    }
  }
}

Nota: Il TMDB_AUTH_TOKEN può essere impostato a un valore casuale per ora, poiché le chiamate API TMDB sono gratuite e non richiedono autenticazione obbligatoria.

Testing Strategy

The project uses Jest for comprehensive testing, including:

Unit Tests: Validate individual handler functions, input validation, and response formatting (see tests/unit/handlers.test.js).
Integration Tests: Test API interactions with mocked responses, error handling, and network failures (see tests/integration/api.test.js).
Protocol Tests: Ensure MCP protocol compliance, including tool listing and calling (see tests/protocol/mcp.test.js).

Run the test suite with:

bash

npm test

For watch mode:

bash

npm run test:watch

Project Structure

wizzy-mcp-tmdb/
├── mcp-tmdb-server.js          # Main MCP server implementation
├── package.json                # Project configuration and dependencies
├── MCP_GUIDE.md                # Detailed MCP integration guide
├── babel.config.cjs            # Babel configuration for Jest
├── tests/
│   ├── unit/
│   │   └── handlers.test.js    # Unit tests for handlers
│   ├── integration/
│   │   └── api.test.js         # Integration tests for API calls
│   └── protocol/
│       └── mcp.test.js         # MCP protocol compliance tests
└── tests/fixtures/             # Mock data for tests
    ├── movieDetails.json
    ├── searchMultiResponse.json
    └── trendingAllResponse.json

Contributing

We welcome contributions! Please follow these guidelines:

Fork the repository.
Create a feature branch.
Make your changes and add tests.
Ensure all tests pass.
Submit a pull request.

License

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

Acknowledgments

Thanks to The Movie Database (TMDB) for providing the API.
Built using the Model Context Protocol SDK.

Contact

For questions or support, please open an issue on GitHub.

Star History

Repository Owner

drakonkat

User

Repository Details

Language JavaScript

Default Branch master

Size 91 KB

Contributors 1

License MIT License

MCP Verified Nov 11, 2025

Programming Languages

JavaScript

100%

Related MCPs

Discover similar Model Context Protocol servers

MCP-Twikit

A Model Context Protocol server for Twitter search and interaction.

MCP-Twikit is an MCP-compliant server that enables interaction with the Twitter platform via the Model Context Protocol. It supports functions such as searching tweets, analyzing sentiments across accounts, and retrieving a user's Twitter timeline. The tool is designed for integration with AI clients to facilitate structured, context-aware access to Twitter data.

⭐ 211
MCP
adhikasp/mcp-twikit

@f4ww4z/mcp-mysql-server

Standardized MySQL operations server for Model Context Protocol environments.

Provides a Model Context Protocol server that allows AI models to interact with MySQL databases through a standardized interface. Supports secure connection, prepared statements, and robust error handling. Enables models to connect, query, execute statements, list tables, and describe schema with simple commands. Designed for seamless integration with tools like Smithery and evaluation frameworks.

⭐ 130
MCP
f4ww4z/mcp-mysql-server

tavily-search MCP server

A search server that integrates Tavily API with Model Context Protocol tools.

tavily-search MCP server provides an MCP-compliant server to perform search queries using the Tavily API. It returns search results in text format, including AI responses, URLs, and result titles. The server is designed for easy integration with clients like Claude Desktop or Cursor and supports both local and Docker-based deployment. It facilitates AI workflows by offering search functionality as part of a standardized protocol interface.

⭐ 44
MCP
Tomatio13/mcp-server-tavily

MCP-Typescribe

An MCP server for serving TypeScript API context to language models.

MCP-Typescribe is an open-source implementation of the Model Context Protocol (MCP) focused on providing LLMs with contextual, real-time access to TypeScript API documentation. It parses TypeScript (and other) definitions using TypeDoc-generated JSON and serves this information via a queryable server that supports tools used by AI coding assistants. The solution enables AI agents to dynamically explore, search, and understand unknown APIs, accelerating onboarding and supporting agentic behaviors in code generation.

⭐ 45
MCP
yWorks/mcp-typescribe

IP Find MCP Server

A Model Context Protocol server for IP location lookups by AI assistants.

IP Find MCP Server acts as a Model Context Protocol (MCP) server, allowing AI assistants to access geolocation data from the IP Find API. It connects the IP Find API with AI tools, enabling the retrieval of IP address location information in standardized contexts. Designed for integration with MCP clients such as the Claude Desktop App, it simplifies configuration and secure API key management. The server is certified by MCPHub.

⭐ 2
MCP
ipfind/ipfind-mcp-server

Brave Search MCP Server

MCP-compliant server providing advanced Brave Search API tools via STDIO and HTTP.

Implements a Model Context Protocol (MCP) server for integrating with the Brave Search API, offering tools for web, local business, image, video, and news searches along with AI-powered summarization. Supports both STDIO and HTTP transports and adheres to established MCP conventions for context management. Provides structured tool schemas and customizable parameters to handle sophisticated search queries and results. Enables advanced filtering, multi-type result aggregation, and seamless integration for AI model workflows.

⭐ 337
MCP
brave/brave-search-mcp-server

View all Alternatives

Didn't find tool you were looking for?

Search AI Tools

wizzy-mcp-tmdb

Key Features

Use Cases

README

wizzy-mcp-tmdb

Project Overview and Purpose

Key Features

Installation

Prerequisites

Setup

Usage

Starting the MCP Server

MCP Integration Examples

Search for Movies

Get Movie Details

Get Trending Content

MCP Client Integration

Testing Strategy

Project Structure

Contributing

License

Acknowledgments

Contact

Star History

Repository Owner

Repository Details

Programming Languages

Tags

Related MCPs