moviefinder-mcp
Provides tools to search movies and TV shows, retrieve detailed information including cast, directors, and trailers, get recommendations and similar movies, view trending content, find streaming providers, and discover movies by genre, rating, year, and sort order.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@moviefinder-mcpWhat are the trending movies this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
moviefinder-mcp
An MCP server that wraps The Movie Database (TMDB) API. Built with @modelcontextprotocol/sdk and stdio transport.
Tools
Tool | Description |
| Search movies by title, optional |
| Search TV shows by title. |
| Full movie details with top cast, directors, and trailer. |
| TMDB recommendations for a movie. |
| Movies similar to a given movie. |
| Trending |
| Streaming / rental / purchase providers for a movie (default country |
| Discover by genre name, min rating, year, and sort order. |
All tools return summarized JSON (id, title, year, overview, rating, poster URL, etc.) — the noisy raw TMDB fields are stripped.
Related MCP server: wizzy-mcp-tmdb
Setup
1. Get a TMDB API token
Create a free account at https://www.themoviedb.org/.
Visit https://www.themoviedb.org/settings/api and copy the API Read Access Token (v4). This is a long JWT — it is not the v3 API key.
2. Install and build
npm install
npm run build3. Configure environment
Copy .env.example to .env and paste your token:
cp .env.example .envTMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...4. Run the server
npm startThe server speaks MCP over stdio and is meant to be launched by an MCP client (such as Claude Desktop), not run interactively.
Register with Claude Desktop
Add an entry to claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"moviefinder": {
"command": "node",
"args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
"env": {
"TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
}
}
}
}Restart Claude Desktop after editing the config. The moviefinder tools will then appear in any conversation.
Scripts
Script | What it does |
| Compiles TypeScript to |
| Runs the compiled server ( |
| TypeScript watch mode. |
Error handling
The server returns helpful messages for common TMDB failures:
401 — token missing or wrong key type (must be v4 read access token).
404 — the requested movie / resource does not exist.
429 — rate limited; the
Retry-Aftervalue is included when present.
Notes
Genre list is fetched once from
/genre/movie/listand cached in memory.Poster URLs use
https://image.tmdb.org/t/p/w500.No database, no logging framework — by design.
Available Tools
8 toolsdiscover_moviesC
Discover movies by genre name, minimum rating, year, and sort order. Genre is resolved by name (e.g. 'Action').
| Name | Required | Description | Default |
|---|---|---|---|
| genre | No | ||
| min_rating | No | ||
| year | No | ||
| sort_by | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It only states that genre is resolved by name, but lacks details on return type, pagination, error handling, or what happens if no movies match.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with verb and parameters, no extra words. Highly efficient for the information it provides.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters, the description is too sparse. It omits any mention of output format, pagination, or common behavior for filter tools, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description names all four parameters and clarifies that genre is a resolved name. However, it does not explain valid values for min_rating (0-10), year range, or sort_by options, which are already in schema but not repeated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool discovers movies by genre, rating, year, and sort order. However, it does not differentiate from sibling tools like search_movies or get_trending, which could be confused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies filtering but lacks context like 'for exploring movies by criteria' and does not mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_movie_detailsA
Get full details for a movie, including top cast, directors, and trailer.
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, requires authentication, or has any side effects. It lacks details about limitations or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 14 words, front-loaded with the core purpose. No redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one integer ID) and no output schema, the description gives a reasonable hint about output (cast, directors, trailer). It is mostly complete for a retrieval tool, though more detail on other fields would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but only implicitly references the movie_id via the tool name. It adds no clarification on how to obtain the ID or format expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details for a specific movie, listing examples (top cast, directors, trailer) that distinguish it from sibling tools like search_movies or get_recommendations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing detailed information about a single movie, but does not explicitly state when not to use or provide alternatives. The tool's straightforward purpose makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_recommendationsC
Get TMDB recommendations for a given movie.
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states it 'gets recommendations', but does not mention whether this is a read-only operation, any required permissions, or what the recommendations are based on (e.g., TMDB algorithm). The agent gains little insight into side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no wasted words. However, it is so terse that it omits essential context, which reduces its value for concise communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the single parameter, the description should at least outline what the recommendations consist of or how they are generated. It fails to provide enough context for an agent to understand the tool's capabilities fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage (no descriptions). The description does not explain the 'movie_id' parameter beyond what the schema provides (integer, >0). It does not clarify where to obtain the ID or what it represents (e.g., TMDB movie ID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets recommendations for a given movie, using a specific verb and resource. However, it does not explicitly distinguish from the sibling tool 'get_similar', which could cause confusion about the difference between recommendations and similar movies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_similar' or 'discover_movies'. The description lacks any context about typical use cases or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_similarC
Get movies similar to a given movie.
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It does not disclose how 'similar' is determined, whether results are limited, or any behavioral traits like ordering, pagination, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, highly concise. However, it sacrifices necessary information for brevity, making it only minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a single parameter, the description fails to provide sufficient context such as return format, result count, or typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description does not add meaning beyond the schema. It does not explain what movie_id refers to (e.g., source, format) despite schema having only one parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Get movies similar to a given movie.' It identifies the input (a movie) and the output (similar movies), but does not differentiate from sibling tools like get_recommendations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., get_recommendations). No context, prerequisites, or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_trendingC
Get trending movies, TV shows, or both.
| Name | Required | Description | Default |
|---|---|---|---|
| media_type | Yes | ||
| time_window | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states it 'gets' data, but does not disclose whether results are paginated, cached, limited, or if network calls are made. The description is too sparse to inform safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action. However, it is too terse and could be expanded to include parameter context or output hints without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, the description should at least hint at what the tool returns (e.g., a list of trending items). It does not, leaving the response format ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not add any meaning to the parameters. It hints at media_type by mentioning movies/TV shows, but does not explain the time_window parameter or the exact allowed values. The description fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves trending movies, TV shows, or both, matching the media_type enum. The verb 'get' and resource 'trending' are specific. However, it doesn't differentiate from sibling tools like discover_movies, which may also have trending content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as discover_movies or search_movies. There is no mention of use cases, limitations, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_moviesA
Search TMDB for movies by title. Optionally filter by release year.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| year | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only says 'search' without disclosing behavior like rate limits, pagination, or error handling. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple search tool, but could mention result format or common constraints. Since no output schema, description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description explains that query is for title search and year is an optional filter, adding meaning beyond schema constraints. Schema had 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches TMDB movies by title, with optional year filter. It distinguishes from siblings like discover_movies and get_movie_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this over sibling tools like discover_movies or search_tv. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_tvB
Search TMDB for TV shows by title.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It merely states the action without mentioning pagination, language constraints, result limits, or any other behavioral traits beyond the basic search function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the essential purpose. Every word earns its place, and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with one parameter and no output schema, the description is minimally adequate. However, it lacks context on result format, sorting, or any filtering parameters, which would enhance completeness given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'query' is only specified in the schema with a minLength constraint. The description does not add any semantics (e.g., case sensitivity, fuzzy matching, language) beyond what the schema provides, and schema description coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('TMDB for TV shows'), and the method ('by title'). It directly differentiates from the sibling 'search_movies' tool, which searches movies instead of TV shows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'discover_movies' or 'get_trending'. There is no mention of when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
where_to_streamA
Find streaming, rental, and purchase providers for a movie in a given country (default US). Data sourced from JustWatch via TMDB.
| Name | Required | Description | Default |
|---|---|---|---|
| movie_id | Yes | ||
| country_code | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions data sourcing from JustWatch via TMDB but does not disclose what happens when no providers are found, potential rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key action, and every sentence adds value. No wasteful words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain the return format or structure. It also lacks information about error handling or edge cases. Adequate for a simple lookup but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds that country_code defaults to US. However, it does not explain the format or constraints of movie_id or country_code beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds streaming, rental, and purchase providers for a movie, specifying a default country and data source. This verb+resource combination is specific and distinguishes it from siblings like get_movie_details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding where to watch a movie but does not explicitly compare with alternatives like get_movie_details or search_movies. No direct 'when to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
8 tool updates
v0.1.0- First observed
discover_movies - First observed
get_movie_details - First observed
get_recommendations - First observed
get_similar - First observed
get_trending - First observed
search_movies - First observed
search_tv - First observed
where_to_stream
TDQS
Each tool targets a distinct action: discover by criteria, get full details, get recommendations, get similar, get trending, search movies, search TV, and find streaming providers. No meaningful overlap exists.
All tool names follow a consistent verb_noun snake_case pattern (e.g., discover_movies, get_movie_details, search_tv). 'where_to_stream' is a minor deviation but still clearly readable.
8 tools cover the main use cases for a movie/TV finder: discovery, search, details, trends, recommendations, similar, and streaming info. The scope is well-balanced.
The set covers most core movie operations, but lacks get_tv_details for TV shows. Other gaps like user ratings or reviews are acceptable for the stated purpose.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
TheGamesDB MCP — wraps TheGamesDB API (thegamesdb.net), a community
The official MCP Server for the Mux API
Related MCP Servers
- AlicenseDqualityDmaintenanceAn MCP server that allows users to search for movies, get detailed information, receive genre-based recommendations, and discover popular/trending films using OMDb and TMDb APIs.525MIT
- AlicenseAqualityFmaintenanceA MCP server for The Movie Database API that enables AI assistants to search and retrieve movie, TV show, and person information.23134MIT
- FlicenseAqualityDmaintenanceAn MCP server that wraps the TMDB API, enabling search of movies and TV shows, retrieval of details, trending titles, recommendations, and streaming provider information.8-
- FlicenseNot gradedqualityDmaintenanceA robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AmeliaMiddleton/Php1mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server