内容
# tmdb-mcp
[](https://www.npmjs.com/package/tmdb-mcp)
[](https://github.com/Grinv/tmdb-mcp/actions/workflows/ci.yml)
[](LICENSE)
一个适用于 **The Movie Database (TMDB)** 的 [MCP](https://modelcontextprotocol.io) 服务器：搜索和查找电影、电视节目和人物，并读取 **IMDb / Rotten Tomatoes / Metacritic** 评分（通过 [OMDb](https://www.omdbapi.com/)）在同一个调用中。
服务器通过stdio使用标准MCP，因此它适用于任何MCP客户端（Claude Desktop/Code、Cursor、VS Code、Cline等）。
## 安装
将其添加到您的MCP客户端配置中。唯一需要的凭证是TMDB v4 **读取访问令牌**；`OMDB_API_KEY`（评分）和`TMDB_LANGUAGE` / `TMDB_REGION`（本地化）是可选的。
**通过npx（无需安装）：**
```json
{
"mcpServers": {
"tmdb": {
"command": "npx",
"args": ["-y", "tmdb-mcp"],
"env": {
"TMDB_API_TOKEN": "您的tmdb-v4读取访问令牌（必填）",
"OMDB_API_KEY": "您的omdb密钥（可选 — IMDb/RT/Metacritic评分）",
"TMDB_LANGUAGE": "en-US（可选 — 本地化，例如ru-RU）",
"TMDB_REGION": "US（可选 — 地区认证，例如RU）"
}
}
}
}
```
> 将每个值替换为您自己的值。只有`TMDB_API_TOKEN`是必需的 — 删除标记为可选的行，如果您不需要它们。
**作为`.mcpb`包（最适合Claude Desktop）：** 从 [最新版本](https://github.com/Grinv/tmdb-mcp/releases/latest) 下载 `tmdb-mcp.mcpb`，然后在Claude Desktop的扩展程序中打开/拖入它。这是一个自包含的包（不需要Node或npm）；在安装对话框中输入令牌和可选字段。重新下载并重新安装以更新。
**从源代码：** `git clone`，然后 `npm ci && npm run build`，并指向客户端 `"command": "node"`，`"args": ["/ABS/PATH/tmdb-mcp/dist/index.js"]` 和上面的相同 `env`。
参见 [docs/clients.md](docs/clients.md) 了解每个客户端的详细信息和所有可调参数。
## 功能
| 工具 | 目的 |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `search_movies` / `search_tv` / `search_people` | 按名称查找标题/人员 → TMDB id |
| `search_multi` | 同时搜索电影、电视和人员（每行都有 `media_type`） |
| `get_movie` / `get_tv` | 完整详情 **+ IMDb/RT/Metacritic评分** （使用 `include_ratings`切换） |
| `get_person` | 传记、部门、链接 |
| `get_movie_credits` / `get_tv_credits` | 主要演员和主要剧组 |
| `get_movie_recommendations` / `get_tv_recommendations` | 相似标题 |
| `get_trending` | 当前热门（电影/TV/人物，当天或当周） |
| `get_movie_genres` / `get_tv_genres` | 类型id ↔ 名称参考 |
| `discover_movies` / `discover_tv` | 按类型、年份/日期范围、评分、演员/剧组、关键词、提供商、认证等筛选 |
| `get_watch_providers` | 按地区提供流媒体/租赁/购买（通过TMDB的JustWatch） |
| `get_person_credits` | 人员的影视作品（演员和剧组） |
| `get_videos` | 预告片/预映/片段（YouTube链接） |
| `find_by_imdb_id` | 解析IMDb id → TMDB电影/TV/人物 |
| `get_tv_season` / `get_tv_episode` | 季集列表/单集详情 |
| `search_keywords` | 解析关键词名称 → `discover_*`的id |
| `get_ratings` | 按IMDb id或标题获取IMDb/RT/Metacritic评分（独立） |
**主干 vs. 丰富。** TMDB是主要来源（搜索、元数据、人物、趋势）。OMDb是可选的丰富：`get_movie`/`get_tv`将TMDB返回的`imdb_id`链接到OMDb查找，以便在一次调用中返回评分。
如果没有OMDb密钥，TMDB数据仍然有效；`ratings`字段仅报告它未配置。
**本地化。** 设置 `TMDB_LANGUAGE`（例如 `ru-RU`）和 `TMDB_REGION`（例如 `RU`）以获取本地化的标题/概述/类型名称和地区特定的认证。大多数工具还接受每个调用的 `language`覆盖。
## 凭证
- **`TMDB_API_TOKEN`** （必填）：TMDB v4 **"读取访问令牌"**，来自 <https://www.themoviedb.org/settings/api>。作为 `Authorization: Bearer …` 发送。
- **`OMDB_API_KEY`** （可选）：来自 <https://www.omdbapi.com/apikey.aspx> 的免费密钥 — 启用评分丰富。
参见 [docs/clients.md](docs/clients.md) 了解每个客户端的配置片段。
## 开发
```sh
npm install
npm run build # 类型检查 + 捆绑到 dist/index.js
npm test # node:test（模拟，离线）
npm run lint
npm run format
npm run check:api # 上游健康检查（需要环境凭证）
npm run inspector # 在MCP检查器下运行
```
运行时需要 Node ≥ 18。贡献者/代理指南位于 [AGENTS.md](AGENTS.md)。
## 更新
- **`.mcpb` 包：** 从发布页面下载新包并重新安装。
- **从源代码：** `git pull && npm ci && npm run build`。
- **npx：** 未固定的 `npx -y tmdb-mcp` 在下一次运行时获取最新版本。
本产品使用TMDB API，但不被TMDB认可或认证。
## 许可证
[MIT](LICENSE) © Grinv
