TMDB MCP Server
A Model Context Protocol (MCP) server that provides access to The Movie Database (TMDB) API. This server enables Claude and other MCP clients to search for movies, TV shows, and people, as well as get detailed information and recommendations.
🌟 Now available on the Official MCP Registry
Quick Start
Get started in seconds with npm:
# Install globally
npm install -g tmdb-mcp-server
# Or use with npx (no installation needed)
npx tmdb-mcp-server
Get your free TMDB API token: https://www.themoviedb.org/settings/api
Features
🎬 Movie Tools
- search_movies - Search for movies by title
- get_movie_details - Get detailed information about a specific movie (budget, revenue, runtime, genres, etc.)
- discover_movies - Discover movies with advanced filters (genre, language, year range, rating, sorting)
- get_recommendations - Get movie recommendations based on a specific movie
- get_movie_credits - Get cast and crew information for a movie
📺 TV Show Tools
- search_tv_shows - Search for TV shows by name
- get_tv_details - Get detailed information about a specific TV show (seasons, episodes, networks, etc.)
- discover_tv_shows - Discover TV shows with advanced filters (genre, language, year, rating, sorting)
- get_tv_recommendations - Get TV show recommendations based on a specific show
- get_tv_credits - Get cast and crew information for a TV show
👥 People Tools
- search_people - Search for actors, directors, and other entertainment industry professionals
- get_person_details - Get detailed biographical information about a person
🔥 Trending
- get_trending - Get daily or weekly trending movies, TV shows, or people
Installation
Option 1: npm (Recommended)
Install from npm registry:
npm install -g tmdb-mcp-server
That's it! No build step required.
Option 2: From Source (For Development)
Prerequisites:
- Node.js (v18 or higher)
- A TMDB API access token (get one free at TMDB)
Steps:
- Clone the repository:
git clone https://github.com/tcehjaava/tmdb-mcp-server.git
cd tmdb-mcp-server
- Install dependencies:
npm install
- Create a
.envfile with your TMDB access token:
cp .env.example .env
# Edit .env and add your TMDB_ACCESS_TOKEN
- Build the server:
npm run build
Usage
With Claude Desktop
Add the server to your Claude Desktop configuration:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
If installed via npm:
{
"mcpServers": {
"tmdb": {
"command": "npx",
"args": ["-y", "tmdb-mcp-server"],
"env": {
"TMDB_ACCESS_TOKEN": "your_tmdb_access_token_here"
}
}
}
}
If installed from source:
{
"mcpServers": {
"tmdb": {
"command": "node",
"args": ["/absolute/path/to/tmdb-mcp-server/build/index.js"],
"env": {
"TMDB_ACCESS_TOKEN": "your_tmdb_access_token_here"
}
}
}
}
With Other MCP Clients
The server runs on stdio by default, making it compatible with any MCP client that supports stdio transport.
Remote Deployment (HTTP Mode)
The server also supports Streamable HTTP transport for remote deployment:
MCP_TRANSPORT=http PORT=3000 node build/index.js
See TRANSPORT.md for detailed deployment instructions for platforms like Railway.
Development
Local Development
Run the server in watch mode for development:
npm run watch
Debugging
Use the MCP Inspector for debugging:
npm run inspector
The Inspector provides a web interface for testing and debugging MCP tools.
Code Formatting
Format code with Prettier:
npm run format
Example Queries
Here are some example queries you can try with Claude:
- "Find Japanese sci-fi movies from 2020 onwards with a rating above 7"
- "What are the top trending movies this week?"
- "Get me recommendations based on The Matrix"
- "Search for Christopher Nolan movies"
- "Show me details about the TV show Breaking Bad"
- "Find Korean dramas with high ratings"
API Rate Limits
TMDB API has rate limits on their free tier:
- 50 requests per second
- Consider implementing caching for production use
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
See CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built with the Model Context Protocol SDK
- Data provided by The Movie Database (TMDB)
- This product uses the TMDB API but is not endorsed or certified by TMDB