电影元数据MCP

作者：stevenaubertin1 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

电影元数据 MCP 服务器

这是一个提供从 TMDB（The Movie Database）和 OMDB（Open Movie Database）API 获取和分析电影元数据工具的 Model Context Protocol (MCP) 服务器。

功能

此 MCP 服务器提供了八个强大的电影和电视节目数据工具：

电影工具

get_movie_by_imdb - 使用 OMDB API（主要）通过 IMDB ID 获取电影数据
search_movies - 按标题搜索电影，可选年份过滤
get_movie_details - 使用 TMDB ID 获取全面的电影信息
get_popular_movies - 发现当前热门电影
analyze_movie_performance - 分析电影表现指标（ROI、评分、受欢迎程度）

电视节目工具

search_tv_shows - 按名称搜索电视节目，可选年份过滤
get_tv_show_details - 使用 TMDB ID 获取全面的电视节目信息
get_tv_episode_details - 获取特定剧集信息（名称、播出日期、概述）

预备条件

Node.js 18 或更高版本
OMDB API 密钥（免费获取于 https://www.omdbapi.com/apikey.aspx） - 主要提供商
TMDB API 密钥（免费获取于 https://www.themoviedb.org/settings/api） - 次要提供商

安装

克隆此仓库：

git clone https://github.com/stevenaubertin/movie-metadata-mcp.git
cd movie-metadata-mcp

安装依赖项：
```
npm install
```
构建项目：
```
npm run build
```

配置

API 密钥

该服务器支持两个 API 提供商，并且可以与其中一个或两个都配置：

OMDB_API_KEY（主要） - 从 OMDB 获取您的免费 API 密钥
- 启用：get_movie_by_imdb
TMDB_API_KEY（次要） - 从 TMDB 获取您的免费 API 密钥
- 启用：search_movies, get_movie_details, get_popular_movies, analyze_movie_performance, search_tv_shows, get_tv_show_details, get_tv_episode_details

注意：建议至少配置一个 API 密钥，但即使没有配置，服务器也会成功启动（显示警告）。只有已配置提供商的工具可用。

Claude Desktop 配置

将此服务器添加到您的 Claude Desktop 配置文件中：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "movie-metadata": {
      "command": "node",
      "args": ["C:\\Users\\x0r\\repo\\movie-metadata-mcp\\dist\\index.js"],
      "env": {
        "TMDB_API_KEY": "your_tmdb_api_key_here",
        "OMDB_API_KEY": "your_omdb_api_key_here"
      }
    }
  }
}

重要：替换 args 中的路径为您构建的 index.js 文件的绝对路径，并添加您的实际 API 密钥。

使用示例

配置好 Claude Desktop 后，您可以请求 Claude 使用这些工具：

搜索电影

"搜索标题中有 'Inception' 的电影"
"查找 1999 年发布的名为 'The Matrix' 的电影"

获取电影详情

"获取 TMDB ID 27205 的电影详细信息"
"电影 ID 550 的制作公司有哪些？"

分析电影表现

"分析《肖申克的救赎》（电影 ID 278）的财务表现"
"展示电影 ID 155 的 ROI 和评分"

获取热门电影

"现在哪些电影很受欢迎？"
"展示热门电影的第 2 页"

根据 IMDB ID 获取电影

"获取 IMDB ID tt0111161 的电影信息"
"查询 IMDB 上的 tt0468569"

搜索电视节目

"搜索标题中有 'Breaking Bad' 的电视节目"
"查找 2005 年开始的名为 'The Office' 的电视节目"

获取电视节目详情

"获取 TMDB ID 1396 的电视节目详细信息"
"电视节目 ID 1668 有多少季？"

获取电视节目剧集详情

"获取《绝命毒师》第 5 季第 14 集的详情"
"电视节目 ID 1396 第 1 季第 1 集的名字是什么？"

可用工具

get_movie_by_imdb（主要 - OMDB）

参数：
- imdb_id（必需）：IMDB ID（例如："tt0111161"）
返回值：来自 OMDB 的电影信息，包括多个来源的评分

search_movies（TMDB）

参数：
- query（必需）：要搜索的电影标题
- year（可选）：发布年份过滤器
返回值：匹配的电影列表，包括 ID、标题、评分和概述

get_movie_details（TMDB）

参数：
- movie_id（必需）：TMDB 电影 ID
返回值：全面的电影数据，包括预算、收入、类型、运行时间、制作公司

get_popular_movies（TMDB）

参数：
- page（可选）：分页的页面编号（默认：1）
返回值：当前热门电影列表

analyze_movie_performance（TMDB）

参数：
- movie_id（必需）：TMDB 电影 ID
返回值：财务分析（ROI、利润）、观众接受度指标、制作信息

search_tv_shows（TMDB）

参数：
- query（必需）：要搜索的电视节目名称
- year（可选）：首次播出年份过滤器
返回值：匹配的电视节目列表，包括 ID、名称、评分和概述

get_tv_show_details（TMDB）

参数：
- tv_id（必需）：TMDB 电视节目 ID
返回值：全面的电视节目数据，包括季数/集数、类型、播出日期、状态

get_tv_episode_details（TMDB）

参数：
- tv_id（必需）：TMDB 电视节目 ID
- season_number（必需）：季数
- episode_number（必需）：集数
返回值：剧集详情，包括名称、播出日期、概述、运行时间和评分

Docker 部署

Docker 提供了最简单的方式运行此 MCP 服务器，无需安装 Node.js 或本地管理依赖项。

预备条件

已安装 Docker（获取 Docker）
您从 TMDB 和/或 OMDB 获取的 API 密钥

快速启动 Docker

步骤 1：获取您的 API 密钥

TMDB API 密钥：在 TMDB 注册（免费，即时批准）
OMDB API 密钥：在 OMDB 注册（免费，邮件激活）

步骤 2：克隆并导航到仓库

git clone https://github.com/stevenaubertin/movie-metadata-mcp.git
cd movie-metadata-mcp

步骤 3：设置环境变量

复制示例环境文件并添加您的 API 密钥：

# 复制示例文件
cp .env.example .env

# 编辑 .env 并替换为您的实际 API 密钥
# TMDB_API_KEY=your_actual_tmdb_key_here
# OMDB_API_KEY=your_actual_omdb_key_here

步骤 4：构建 Docker 镜像

docker build -t movie-metadata-mcp .

这会创建一个轻量级的 Docker 镜像（约 50MB），包含 MCP 服务器及其所有依赖项。

步骤 5：测试服务器

运行容器以交互方式验证其是否正常工作：

docker run -i --rm \
  -e TMDB_API_KEY=your_tmdb_api_key \
  -e OMDB_API_KEY=your_omdb_api_key \
  movie-metadata-mcp

您应该看到以下输出：

在标准 I/O 上运行的服务器
提供商状态（TMDB 和 OMDB 配置）
可用工具列表

按 Ctrl+C 停止。

使用 Docker Compose（推荐）

Docker Compose 简化了从您的 .env 文件运行容器的过程。

步骤 1：确保您的 .env 文件已配置（参见快速启动部分）

步骤 2：启动服务

docker-compose up -d

步骤 3：检查日志以验证其是否正在运行

docker-compose logs -f

您应能看到服务器启动消息和提供商状态。

步骤 4：需要时停止服务

docker-compose down

与 Claude Desktop 集成（Docker）

要使用 Docker 化的 MCP 服务器与 Claude Desktop，您需要配置 Claude 来运行 Docker 容器。

步骤 1：找到您的 Claude Desktop 配置文件

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

步骤 2：先构建 Docker 镜像

docker build -t movie-metadata-mcp .

步骤 3：添加服务器配置

编辑您的 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "movie-metadata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TMDB_API_KEY=your_actual_tmdb_api_key_here",
        "-e", "OMDB_API_KEY=your_actual_omdb_api_key_here",
        "movie-metadata-mcp"
      ]
    }
  }
}

重要：

替换 your_actual_tmdb_api_key_here 和 your_actual_omdb_api_key_here 为您的真实 API 密钥
--rm 标志确保容器在使用后被清理
-i 标志保持标准 I/O 打开用于 MCP 通信

步骤 4：重新启动 Claude Desktop

关闭并重新打开 Claude Desktop 以加载新配置。

步骤 5：验证服务器是否可用

在 Claude Desktop 中，您应该能够请求 Claude 使用电影元数据工具，如：

"搜索关于太空探索的电影"
"获取电影 ID 550（搏击俱乐部）的详细信息"
"现在哪些电影很受欢迎？"

Docker 小贴士

查看服务器启动时可用工具：

服务器日志显示哪些提供商已配置以及哪些工具可用：

电影元数据 MCP 服务器在标准 I/O 上运行
──────────────────────────────────────────────────
提供商状态：
  OMDB: ✓ 已配置
  TMDB: ✓ 已配置

可用工具：5
  - get_movie_by_imdb
  - search_movies
  - get_movie_details
  - get_popular_movies
  - analyze_movie_performance
──────────────────────────────────────────────────

仅使用一个 API 提供商运行：

您可以仅使用 OMDB 或仅使用 TMDB 运行：

# 仅 OMDB - 主要提供商（1 个工具可用）
docker run -i --rm \
  -e OMDB_API_KEY=your_omdb_api_key \
  movie-metadata-mcp

# 仅 TMDB - 次要提供商（4 个工具可用）
docker run -i --rm \
  -e TMDB_API_KEY=your_tmdb_api_key \
  movie-metadata-mcp

修改源代码后重建：

如果您修改了源代码，请重新构建镜像：

docker build -t movie-metadata-mcp .

删除旧镜像：

清理旧镜像以节省空间：

docker image prune -f

开发

# 安装依赖项
npm install

# 构建项目
npm run build

# 开发模式监视
npm run dev

# 直接运行
npm start

平滑降级

MCP 服务器设计为在部分配置下工作：

两个 API 都已配置：所有 8 个工具可用
仅 OMDB 已配置（主要）：1 个工具可用（get_movie_by_imdb）
仅 TMDB 已配置（次要）：7 个工具可用（搜索电影/电视节目、详情、热门、分析、剧集）
未配置任何 API：服务器带有警告启动，0 个工具可用

服务器在启动时将提供商状态记录到标准错误输出，显示哪些 API 已配置以及哪些工具可用。OMDB 列在首位作为主要提供商。

API 请求限制

TMDB：免费层级允许每 10 秒 40 次请求
OMDB：免费层级允许每天 1,000 次请求

许可证

MIT

仓库

GitHub: https://github.com/stevenaubertin/movie-metadata-mcp

贡献

欢迎贡献！请随意提交问题或拉取请求。

分叉仓库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

作者

Steven Aubertin

GitHub: @stevenaubertin