Skip to main content
Glama
AmeliaMiddleton

moviefinder-mcp

moviefinder-mcp

An MCP server that wraps The Movie Database (TMDB) API. Built with @modelcontextprotocol/sdk and stdio transport.

Tools

Tool

Description

search_movies

Search movies by title, optional year filter.

search_tv

Search TV shows by title.

get_movie_details

Full movie details with top cast, directors, and trailer.

get_recommendations

TMDB recommendations for a movie.

get_similar

Movies similar to a given movie.

get_trending

Trending movie / tv / all for day or week.

where_to_stream

Streaming / rental / purchase providers for a movie (default country US).

discover_movies

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

  1. Create a free account at https://www.themoviedb.org/.

  2. 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 build

3. Configure environment

Copy .env.example to .env and paste your token:

cp .env.example .env
TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. Run the server

npm start

The 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.json

  • Windows: %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

npm run build

Compiles TypeScript to dist/.

npm start

Runs the compiled server (node dist/index.js).

npm run dev

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-After value is included when present.

Notes

  • Genre list is fetched once from /genre/movie/list and cached in memory.

  • Poster URLs use https://image.tmdb.org/t/p/w500.

  • No database, no logging framework — by design.

Available Tools

8 tools
discover_moviesC

Discover movies by genre name, minimum rating, year, and sort order. Genre is resolved by name (e.g. 'Action').

ParametersJSON Schema
NameRequiredDescriptionDefault
genreNo
min_ratingNo
yearNo
sort_byNo

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYes

TDQS

A3.7/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYes

TDQS

C2.6/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters1/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYes

TDQS

C2.6/5.0
Behavior2/5

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.

Conciseness3/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

search_moviesA

Search TMDB for movies by title. Optionally filter by release year.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
yearNo

TDQS

A3.5/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYes
country_codeNo

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 8 tool updatesv0.1.0
    • First observeddiscover_movies
    • First observedget_movie_details
    • First observedget_recommendations
    • First observedget_similar
    • First observedget_trending
    • First observedsearch_movies
    • First observedsearch_tv
    • First observedwhere_to_stream

TDQS

A3.5/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessSyncing

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

Related MCP Servers

  • A
    license
    D
    quality
    D
    maintenance
    An 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.
    5
    25
    MIT
  • A
    license
    A
    quality
    F
    maintenance
    A MCP server for The Movie Database API that enables AI assistants to search and retrieve movie, TV show, and person information.
    23
    13
    4
    MIT
  • F
    license
    A
    quality
    D
    maintenance
    An 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
    -
  • F
    license
    Not graded
    quality
    D
    maintenance
    A robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.
    -

Latest Blog Posts

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