Skip to main content
Glama
AmeliaMiddleton

moviefinder-mcp

moviefinder-mcp

An MCP server that wraps the TMDB API so an MCP-aware client (Claude Desktop, Claude Code, etc.) can search movies and TV, look up details, find what's trending, get recommendations, and check where a title is streaming.

Tools

Tool

Description

search_movies

Search movies by title; optional year.

search_tv

Search TV shows by name.

get_movie_details

Movie details with cast, director, and trailer URL.

get_recommendations

TMDB recommendations for a movie ID.

get_similar

Movies similar to a movie ID.

get_trending

Trending movie / tv / all for day or week.

where_to_stream

Watch providers (stream / rent / buy) by country (default US).

discover_movies

Discover by genre name, min_rating, year, sort_by.

All tools return summarized JSON (id, title, year, overview, rating, poster URL, plus tool-specific fields) instead of raw TMDB payloads.

Related MCP server: wizzy-mcp-tmdb

Setup

Requirements: Node 20+.

npm install
cp .env.example .env
# edit .env and paste your TMDB v4 read access token
npm run build
npm start    # runs the compiled server over stdio

Getting a TMDB API key

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

  2. Open https://www.themoviedb.org/settings/api.

  3. Copy the API Read Access Token (v4 auth)not the v3 API key.

  4. Put it in .env as TMDB_API_KEY=....

The server sends it as Authorization: Bearer <token>.

Register with Claude Desktop

Edit 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": "your_v4_read_access_token_here"
      }
    }
  }
}

Restart Claude Desktop. The tools above will appear under the moviefinder server.

Notes

  • The genre list (/genre/movie/list) is fetched once and cached in memory for discover_movies.

  • 401 / 404 / 429 responses are surfaced with actionable messages.

  • Inputs are validated with zod before any TMDB call.

Available Tools

8 tools
discover_moviesC

Discover movies by genre, minimum rating, year, and sort order.

ParametersJSON Schema
NameRequiredDescriptionDefault
genreNoGenre name (e.g. 'Action', 'Comedy').
min_ratingNoMinimum vote average.
yearNoPrimary release year.
sort_byNoTMDB sort key, e.g. 'popularity.desc', 'vote_average.desc', 'primary_release_date.desc'.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, and the description does not disclose behavioral traits such as idempotency, authorization needs, or side effects. It only states the action without explaining what happens during invocation.

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 sentence with no redundant words. It front-loads the action and lists parameters efficiently.

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 lack of output schema and annotations, the description is insufficient. It omits information about pagination, result format, default behavior, or any post-condition. For a discovery tool, more context is needed to fully understand output and constraints.

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?

The input schema has 100% coverage with descriptions for all parameters. The description adds no extra meaning beyond listing the parameter names, so it meets the baseline expectation.

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 tool's purpose (discovering movies) and lists the filtering criteria (genre, minimum rating, year, sort order). It distinguishes from siblings like 'search_movies' and 'get_trending' by implying a filtered discovery use case, but does not explicitly differentiate.

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?

The description provides no guidance on when to use this tool versus alternatives like 'search_movies' or 'get_recommendations'. No context about prerequisites or limitations is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_movie_detailsA

Fetch full details for a movie including cast, director, and trailer URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYesTMDB movie ID.

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 must cover behavioral traits. It only states what fetches; it does not disclose error behavior, authentication needs, rate limits, or the full return structure.

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, clear, and front-loaded sentence with no unnecessary words. Every part contributes to understanding the tool's purpose.

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 tool with one parameter and no output schema, the description is adequate but lacks details on return format, error handling, or links to documentation. It covers the basic purpose but not the full context.

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?

The input schema already documents the parameter 'movie_id' with a description (100% coverage). The tool description adds value by explaining what details (cast, director, trailer) will be retrieved, giving context for the parameter's usage.

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 explicitly states the verb 'Fetch', the resource 'full details for a movie', and specific attributes (cast, director, trailer URL). This clearly distinguishes it from sibling tools like search_movies or get_trending.

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 when you need detailed info for a specific movie, but it does not mention when not to use it (e.g., for lists, use discover_movies) or provide explicit alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recommendationsB

Get TMDB's recommendations for users who liked the given movie.

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYesTMDB movie ID to base recommendations on.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as whether the operation is read-only, any rate limits, or what happens if the movie ID is invalid. The description solely states the action without revealing underlying behavior.

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 of 12 words, which is highly efficient and front-loaded. Every word is essential, and there is no redundancy.

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?

Given the tool has only one parameter and no output schema, the description is functional but lacks details about the return format, pagination, or limitations. It is minimally complete but could be improved with additional context.

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?

The input schema has 100% description coverage for the single parameter 'movie_id', so the schema already explains the parameter. The description adds no additional semantic value beyond the schema, achieving the baseline score.

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 'Get' and the resource 'TMDB's recommendations for users who liked the given movie', making the purpose unambiguous. However, it does not differentiate from the sibling tool 'get_similar', which likely serves a similar function, so the purpose clarity is slightly diminished.

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?

The description provides no guidance on when to use this tool versus alternatives like 'get_similar' or 'discover_movies'. No usage context or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_similarA

Get movies similar to the given movie (matched on keywords/genres).

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYesTMDB movie ID to find similar titles for.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must replace them. It only mentions matching on keywords/genres, lacking details on side effects, limits, or authentication requirements. The tool appears read-only but is not stated.

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?

A single sentence that is concise and front-loaded, containing only essential information without any wasted 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?

Given no output schema, the description could mention return format or pagination. For a simple tool, it meets minimal requirements but lacks completeness in expected behavior.

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?

Schema covers the parameter with a description. The description adds 'matched on keywords/genres', explaining the similarity logic beyond the schema, which provides additional meaning.

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 'Get movies similar' and specifies matching on keywords/genres, distinguishing it from siblings like 'get_recommendations' which may use different criteria.

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 use for similarity-based queries but does not explicitly say when to use versus alternatives like 'get_recommendations' or 'discover_movies'. No guidance on 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.

search_moviesB

Search TMDB for movies by title, optionally filtered by release year.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesMovie title or keywords.
yearNoRelease year filter.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as pagination, rate limits, result limits, or handling of empty results. For a search tool, these are important but missing.

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 with no redundant information. It is front-loaded and concise, earning its place.

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?

The tool has no output schema and no description of return values. Given the lack of annotations and missing behavioral details (e.g., pagination), the description is insufficient for complete understanding.

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?

The input schema covers both parameters with descriptions (100% coverage). The description repeats 'by title' and 'optionally filtered by release year', adding minimal new meaning beyond the schema.

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 verb 'search', the resource 'movies', and the optional filter by release year. It distinguishes from siblings like 'discover_movies' which implies more complex filtering.

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 like 'discover_movies' or 'get_trending'. The description only mentions optional filtering but does not provide context for tool selection.

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 name.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesTV show title or keywords.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, result format, or side effects. It only states the search action.

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?

A single sentence containing only essential information. It is appropriately sized and front-loaded, though could be expanded slightly without losing conciseness.

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 lack of output schema and annotations, the description should provide more context about return values, pagination, or limitations. It is insufficient for an AI to fully understand the tool's behavior.

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 100% with the 'query' parameter already described as 'TV show title or keywords.' The description adds no additional meaning beyond the schema, hence baseline 3.

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 verb 'search', resource 'TMDB for TV shows', and search criterion 'by name'. It distinguishes from sibling tools like 'search_movies' and 'discover_movies' which target 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 on when to use this tool versus alternatives like 'search_movies' or 'discover_movies'. The description lacks explicit context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

where_to_streamA

Show streaming, rental, and purchase options for a movie in a given country (defaults to US).

ParametersJSON Schema
NameRequiredDescriptionDefault
movie_idYesTMDB movie ID.
country_codeNoISO 3166-1 alpha-2 country code (defaults to US).

TDQS

A3.5/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 behavioral traits. It only states the tool shows options, but does not disclose if it's read-only, authentication needs, rate limits, error handling (e.g., missing movie), or output format. Limited 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?

The description is a single, clear sentence that front-loads the action (Show). It is concise and contains no unnecessary words, earning its place efficiently.

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 tool with two parameters and no output schema, the description is adequate but lacks details on error scenarios (e.g., invalid movie_id) or behavior when no options exist. It is minimally complete but could be more robust.

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 100% (both parameters described in input schema). The description adds minor context by stating the default country (US), which aligns with the schema's description. It does not add significant new meaning beyond the schema.

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's purpose: showing streaming, rental, and purchase options for a movie in a given country. It uses a specific verb and resource, and distinguishes from sibling tools (e.g., discover_movies, get_movie_details) by focusing on availability options.

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 when to use the tool (to check availability of a movie) and mentions the default country, but does not explicitly state when not to use it or provide alternatives. Usage guidance is implied but not comprehensive.

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.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose. Discovery, details, recommendations, similar, trending, search (movies and TV), and streaming options are all well-separated, with no ambiguous overlaps.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern using snake_case (e.g., discover_movies, get_movie_details, search_movies). The naming is predictable and clear.

Tool Count5/5

With 8 tools, the scope is well-balanced for a movie/TV information server. Each tool addresses a distinct need without being excessive or insufficient.

Completeness4/5

The set covers key functionalities: search, discover, trending, details, recommendations, similar, and streaming. A minor gap is the lack of TV show details (only search_tv exists), but overall coverage is solid.

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 Movie Database (TMDB) API, enabling search for movies and TV shows, retrieval of movie details, recommendations, similar movies, trending content, streaming providers, and movie discovery.
    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/Mcp1testtypescript'

If you have feedback or need assistance with the MCP directory API, please join our Discord server