Skip to main content
Glama
moviefinder-mcp

moviefinder-mcp

moviefinder-mcp

一个封装了 The Movie Database (TMDB) API 的 MCP 服务器。使用 @modelcontextprotocol/sdk 和 stdio 传输构建。

工具

工具

描述

search_movies

按标题搜索电影,可选 year 过滤器。

search_tv

按标题搜索电视节目。

get_movie_details

获取完整的电影详情,包括主要演员、导演和预告片。

get_recommendations

获取 TMDB 推荐的电影。

get_similar

获取与给定电影相似的电影。

get_trending

获取 day 或 week 的热门 movie / tv / all 内容。

where_to_stream

获取电影的流媒体/租赁/购买提供商(默认国家为 US)。

discover_movies

按流派名称、最低评分、年份和排序方式发现电影。

所有工具均返回摘要后的 JSON(ID、标题、年份、概述、评分、海报 URL 等)——已剔除冗余的原始 TMDB 字段。

Related MCP server: wizzy-mcp-tmdb

设置

1. 获取 TMDB API 令牌

  1. 在 https://www.themoviedb.org/ 注册一个免费账户。

  2. 访问 https://www.themoviedb.org/settings/api 并复制 API Read Access Token (v4)。这是一个很长的 JWT —— 不是 v3 API 密钥。

2. 安装与构建

npm install
npm run build

3. 配置环境变量

将 .env.example 复制为 .env 并粘贴您的令牌:

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

4. 运行服务器

npm start

该服务器通过 stdio 进行 MCP 通信,旨在由 MCP 客户端(如 Claude Desktop)启动,而非交互式运行。

在 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": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

编辑配置后重启 Claude Desktop。之后 moviefinder 工具将出现在任何对话中。

脚本

脚本

功能

npm run build

将 TypeScript 编译到 dist/。

npm start

运行编译后的服务器 (node dist/index.js)。

npm run dev

TypeScript 监视模式。

错误处理

服务器针对常见的 TMDB 故障返回有用的消息:

  • 401 — 令牌缺失或密钥类型错误(必须是 v4 读取访问令牌)。

  • 404 — 请求的电影/资源不存在。

  • 429 — 速率限制;如果存在,将包含 Retry-After 值。

注意事项

  • 流派列表从 /genre/movie/list 获取一次并缓存在内存中。

  • 海报 URL 使用 https://image.tmdb.org/t/p/w500。

  • 无数据库,无日志框架 —— 这是设计使然。

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').

Inputs: genre, min_rating, year, sort_by.

get_movie_detailsA

Get full details for a movie, including top cast, directors, and trailer.

Inputs: movie_id (required).

get_recommendationsC

Get TMDB recommendations for a given movie.

Inputs: movie_id (required).

get_similarC

Get movies similar to a given movie.

Inputs: movie_id (required).

search_moviesA

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

Inputs: query (required), year.

search_tvB

Search TMDB for TV shows by title.

Inputs: query (required).

where_to_streamA

Find streaming, rental, and purchase providers for a movie in a given country (default US). Data sourced from JustWatch via TMDB.

Inputs: movie_id (required), country_code.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    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
    ResponsivenessOutdated data

    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
      MIT
    • A
      license
      A
      quality
      D
      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 npm
      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
      C
      maintenance
      A robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.
      -