wizzy-mcp-tmdb

Purpose

wizzy-mcp-tmdb is an MCP (Model Context Protocol) server implemented in JavaScript, used to search for and retrieve movie, TV show, and person information from The Movie Database (TMDB). It enables AI clients to access TMDB data through a standardized protocol, making it suitable for scenarios that require AI assistants to query film and television information, retrieve details, or learn about popular content.

Main Capabilities

The server provides three types of tools:

• Search Movies (search_tmdb tool): Performs multi-type searches for movies, TV shows, and people.
• Get Details (get_tmdb_details tool): Retrieves detailed information for a specific entry.
• Trending Content (trending_all tool): Retrieves trending content across all media types.

Usage

Environment Requirements

• Node.js 18 or later (required for global fetch support).
• A TMDB API key (Bearer token) from the administrator, used for the TNL TMDB proxy (production-api.tnl.one).

Installation and Configuration

1. Clone the repository and enter the project directory.
2. Install dependencies:

npm install

1. Set the TMDB API key as an environment variable:

• Windows PowerShell:

$env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

• macOS/Linux：

export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"

Starting the MCP Server

The server communicates via stdio and should be configured in an MCP-capable client (such as an IDE or chat client) with the command node mcp-tmdb-server.js, and with the TMDB_AUTH_TOKEN environment variable set.

MCP Integration Example

When integrating this MCP server into your MCP client (such as an IDE or a compatible chat client), you can follow these steps:

1. If needed, install the npm package:

npm install -g wizzy-mcp-tmdb

1. Create or update mcp.json file in the MCP client, using the following configuration:

{
  "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"
      ]
    }
  }
}

Note: TMDB_AUTH_TOKEN can currently be set to a random value, because TMDB API calls are free and authentication is not strictly required.

Testing Strategy

The project uses Jest for comprehensive testing, including:

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

Run the test suite:

Run watch mode: (No specific test commands are provided in the materials, so none are provided for now.)

Project Structure

(No detailed project structure is provided in the materials, so none is provided for now.)

Contribution Guidelines

Contributions are welcome! Please follow these guidelines:

1. Fork the repository.
2. Create a feature branch.
3. Make changes and add tests.
4. Ensure all tests pass.
5. 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.

Support

If you have questions or need support, please submit an issue on GitHub.