de en es ja ko ru zh

moviefinder-mcp

Name: moviefinder-mcp
Author: AmeliaMiddleton

by AmeliaMiddleton

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

moviefinder-mcp

TMDB API를 래핑하여 MCP 지원 클라이언트(Claude Desktop, Claude Code 등)가 영화 및 TV 프로그램을 검색하고, 세부 정보를 조회하며, 인기 콘텐츠를 찾고, 추천을 받으며, 스트리밍 위치를 확인할 수 있게 해주는 MCP 서버입니다.

도구

도구	설명
`search_movies`	제목으로 영화 검색; 선택 사항으로 `year` 사용 가능.
`search_tv`	이름으로 TV 프로그램 검색.
`get_movie_details`	출연진, 감독, 예고편 URL을 포함한 영화 세부 정보.
`get_recommendations`	영화 ID에 대한 TMDB 추천.
`get_similar`	영화 ID와 유사한 영화.
`get_trending`	`day` 또는 `week` 단위의 `movie` / `tv` / `all` 인기 콘텐츠.
`where_to_stream`	국가별(기본값 `US`) 시청 제공업체(스트리밍 / 대여 / 구매).
`discover_movies`	`genre` 이름, `min_rating`, `year`, `sort_by`를 통한 영화 탐색.

모든 도구는 원시 TMDB 페이로드 대신 요약된 JSON(id, 제목, 연도, 개요, 평점, 포스터 URL 및 도구별 필드)을 반환합니다.

Related MCP server: wizzy-mcp-tmdb

설정

요구 사항: 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

TMDB API 키 발급받기

https://www.themoviedb.org/에서 TMDB 계정을 만듭니다.
https://www.themoviedb.org/settings/api를 엽니다.
**API Read Access Token (v4 auth)**을 복사합니다. (v3 API 키가 아닙니다.)
.env 파일에 TMDB_API_KEY=... 형식으로 저장합니다.

서버는 이를 Authorization: Bearer <token>으로 전송합니다.

Claude Desktop에 등록

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

Claude Desktop을 재시작합니다. 위의 도구들이 moviefinder 서버 아래에 나타납니다.

참고 사항

장르 목록(/genre/movie/list)은 한 번 가져온 후 discover_movies를 위해 메모리에 캐시됩니다.
401 / 404 / 429 응답은 실행 가능한 메시지와 함께 표시됩니다.
입력값은 TMDB 호출 전에 zod를 통해 검증됩니다.

Available Tools

8 tools

discover_moviesC

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

ParametersJSON Schema

Name	Required	Description
`genre`	No	Genre name (e.g. 'Action', 'Comedy').
`min_rating`	No	Minimum vote average.
`year`	No	Primary release year.
`sort_by`	No	TMDB 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

Name	Required	Description	Default
`movie_id`	Yes	TMDB 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

Name	Required	Description	Default
`movie_id`	Yes	TMDB 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

Name	Required	Description	Default
`movie_id`	Yes	TMDB 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.

get_trendingB

Get trending movies, TV, or both, for the day or the week.

ParametersJSON Schema

Name	Required	Description	Default
`media_type`	Yes	Type of media to fetch trends for.
`time_window`	Yes	Trend time window.

TDQS

B3.2/5.0

Behavior2/5

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

No annotations provided, so description must fully disclose behavior. Description only states basic functionality without mentioning response format, pagination, or any side effects. 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 14 words—concise and front-loaded. Could be slightly more informative without being verbose, but still efficient.

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 trending endpoint with two required parameters, the description captures the core purpose. However, lack of output schema and behavioral details leaves agent with incomplete picture.

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 description coverage is 100%, so baseline is 3. Description does not add any additional meaning beyond the enums already described in 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?

Description clearly states the verb (Get), resource (trending), and scope (movies/TV, day/week). It effectively distinguishes from sibling tools like search_movies or discover_movies by focusing on trending content.

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 does not provide context for selection criteria.

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

Name	Required	Description	Default
`query`	Yes	Movie title or keywords.
`year`	No	Release 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

Name	Required	Description	Default
`query`	Yes	TV 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

Name	Required	Description	Default
`movie_id`	Yes	TMDB movie ID.
`country_code`	No	ISO 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.

8 tool updatesv0.1.0May 5, 2026
- 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

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-05-05 02:15 across 8 tools

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

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Tv Maze Mcp
io.github.varvararatta
Unlock a world of television with the TV Maze MCP server. Effortlessly search for shows by name or
Search Entertainment & Media
2
Movies A
io.github.pipeworx-io
Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows, free, no…
Search Entertainment & Media
402
Omdb A
io.github.pipeworx-io
OMDb MCP — IMDB-derived movie / TV / episode data (BYO key)
Entertainment & Media Search
392
Tmdb B
io.github.pipeworx-io
TMDB v3 MCP.
Entertainment & Media Search
3

Related MCP Servers

Movie Search MCP Server
tonderflash
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.
Updated a year ago (2025-07-20 23:12 UTC)
5
9 npm
MIT
wizzy-mcp-tmdb
Entertainment & Media Search
drakonkat
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.
Updated a year ago (2025-09-30 10:59 UTC)
23
13 npm
4
MIT
moviefinder-mcp
Entertainment & Media Search
AmeliaMiddleton
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.
Updated 5 months ago (2026-05-05 01:50 UTC)
8
-
TMDB MCP Server
Entertainment & Media Search
Amruth2507
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.
Updated 6 months ago (2026-04-06 17:28 UTC)
-