moviefinder-mcp
moviefinder-mcp
一个封装了 The Movie Database (TMDB) API 的 MCP 服务器。使用 @modelcontextprotocol/sdk 和 stdio 传输构建。
工具
工具 | 描述 |
| 按标题搜索电影,可选 |
| 按标题搜索电视节目。 |
| 获取完整的电影详情,包括主要演员、导演和预告片。 |
| 获取 TMDB 推荐的电影。 |
| 获取与给定电影相似的电影。 |
| 获取 |
| 获取电影的流媒体/租赁/购买提供商(默认国家为 |
| 按流派名称、最低评分、年份和排序方式发现电影。 |
所有工具均返回摘要后的 JSON(ID、标题、年份、概述、评分、海报 URL 等)——已剔除冗余的原始 TMDB 字段。
Related MCP server: wizzy-mcp-tmdb
设置
1. 获取 TMDB API 令牌
在 https://www.themoviedb.org/ 注册一个免费账户。
访问 https://www.themoviedb.org/settings/api 并复制 API Read Access Token (v4)。这是一个很长的 JWT —— 不是 v3 API 密钥。
2. 安装与构建
npm install
npm run build3. 配置环境变量
将 .env.example 复制为 .env 并粘贴您的令牌:
cp .env.example .envTMDB_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.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..."
}
}
}
}编辑配置后重启 Claude Desktop。之后 moviefinder 工具将出现在任何对话中。
脚本
脚本 | 功能 |
| 将 TypeScript 编译到 |
| 运行编译后的服务器 ( |
| TypeScript 监视模式。 |
错误处理
服务器针对常见的 TMDB 故障返回有用的消息:
401 — 令牌缺失或密钥类型错误(必须是 v4 读取访问令牌)。
404 — 请求的电影/资源不存在。
429 — 速率限制;如果存在,将包含
Retry-After值。
注意事项
流派列表从
/genre/movie/list获取一次并缓存在内存中。海报 URL 使用
https://image.tmdb.org/t/p/w500。无数据库,无日志框架 —— 这是设计使然。
Available Tools
8 toolsdiscover_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).
get_trendingC
Get trending movies, TV shows, or both.
Inputs: media_type (required), time_window (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
Scored across 8 tools
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
Related MCP Connectors
Unofficial Movies MCP — wraps iTunes Search API (movies, free, no auth) and TVmaze API (TV shows…
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)
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.5MIT
- AlicenseAqualityDmaintenanceA MCP server for The Movie Database API that enables AI assistants to search and retrieve movie, TV show, and person information.2313 npm4MIT
- 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 gradedqualityCmaintenanceA robust MCP server that wraps The Movie Database API, enabling LLMs to search movies, get details, popular movies, and recommendations.-