IMDb MCP 服务器

一个 Python 服务器，使用 IMDb API 服务实现电影和电视节目信息的模型上下文协议 (MCP)。

目录

• 概述
• 特性
• 配置
• 工具
  • 搜索工具
  • IMDb ID 工具
  • 配置工具
  • 电影工具
  • 电视节目工具
  • 即将上映工具
  • 印度焦点工具
• 示例提示和响应
• 安装
• 启动服务器
• 技术细节
  • 分页系统
  • 缓存系统
• 限制
• 故障排除
• 许可证

概述

此服务器提供了一套全面的工具，用于通过 IMDb API 访问 IMDb 数据。它充当代理和 IMDb 数据库之间的桥梁，提供有关电影、电视节目、演员、导演等的详细信息。

特性

• 🎬 电影和电视节目搜索功能
• 📋 关于电影和电视节目的详细信息
• 👨‍👩‍👧‍👦 演员和工作人员信息
• 🏆 评分最高和最受欢迎的内容列表
• 💰 票房数据
• 🌍 特定国家/地区的电影信息（特别关注印度电影）
• 🔜 即将上映
• 🔄 高效的响应缓存系统

配置

此服务器需要来自 RapidAPI 的 IMDb API 服务的 API 密钥：

1. 在 RapidAPI 上创建一个帐户
2. 在 RapidAPI 上订阅 IMDb API
3. 设置环境变量：

   RAPID_API_KEY_IMDB=your_api_key_here
   

工具

搜索工具

工具	描述	示例
search_imdb	搜索具有各种过滤选项的电影和电视节目	search_imdb(primary_title="Inception")

IMDb ID 工具

工具	描述	示例
get_imdb_details	检索有关电影或电视节目的详细信息	get_imdb_details(imdb_id="tt1375666")
get_directors	检索电影的导演	get_directors(imdb_id="tt1375666")
get_cast	检索电影的演员	get_cast(imdb_id="tt1375666")
get_writers	检索电影的编剧	get_writers(imdb_id="tt1375666")

配置工具

工具	描述	示例
get_types	获取所有可用的内容类型	get_types()
get_genres	获取所有可用的类型	get_genres()
get_countries	获取所有可用的国家/地区	get_countries()
get_languages	获取所有可用的语言	get_languages()

电影工具

分页（每页 5 个结果）

工具	描述	示例
get_top_250_movies	从 IMDb 获取前 250 部电影	get_top_250_movies()
get_top_box_office_us	获取美国票房记录	get_top_box_office_us()
get_most_popular_movies	获取最受欢迎的电影	get_most_popular_movies()

电视节目工具

分页（每页 5 个结果）

工具	描述	示例
get_top_250_tv_shows	从 IMDb 获取前 250 个电视节目	get_top_250_tv_shows()
get_most_popular_tv_shows	获取最受欢迎的电视节目	get_most_popular_tv_shows()

即将上映工具

分页（每页 5 个结果）

工具	描述	示例
get_upcoming_releases	按国家/地区获取即将上映的电影和电视节目	get_upcoming_releases(country_code="US", type="MOVIE")
get_available_country_codes_for_upcoming_releases	获取即将上映的电影和电视节目的可用国家/地区代码	get_available_country_codes_for_upcoming_releases()

印度焦点工具（分页）

分页（每页 5 个结果）

工具	描述	示例
get_top_rated_malayalam_movies	获取评分最高的 50 部马拉雅拉姆语电影	get_top_rated_malayalam_movies()
get_upcoming_indian_movies	获取最受期待的即将上映的印度电影	get_upcoming_indian_movies()
get_trending_tamil_movies	获取热门泰米尔语电影	get_trending_tamil_movies()
get_trending_telugu_movies	获取热门泰卢固语电影	get_trending_telugu_movies()
get_top_rated_tamil_movies	获取评分最高的 50 部泰米尔语电影	get_top_rated_tamil_movies()
get_top_rated_telugu_movies	获取评分最高的 50 部泰卢固语电影	get_top_rated_telugu_movies()
get_top_rated_indian_movies	获取评分最高的 250 部印度电影	get_top_rated_indian_movies()

示例提示和响应

未来最快上映的 5 部动作片是什么？

我将为您找到即将上映的动作片。

调用 MCP 工具 get_upcoming_releases

现在我将从这些即将上映的电影中寻找动作片：

调用 MCP 工具 get_upcoming_releases

根据搜索结果，以下是未来最快上映的 5 部即将上映的动作片：

1. 我的世界电影（2025 年 4 月 4 日）

   • 类型：动作、冒险、喜剧
   • 描述：四个格格不入的人被拉过一个传送门进入一个立方体的仙境，并与一位专业的工匠一起踏上回家的旅程。

2. 怪异故事（2025 年 4 月 4 日）

   • 类型：动作、冒险、喜剧
   • 描述：四个相互关联的故事，背景设定在 1987 年的加利福尼亚州奥克兰，讲述了对音乐、电影、人物、地点和记忆的热爱。

3. 醒来（2025 年 4 月 4 日）

   • 类型：动作、恐怖
   • 描述：年轻的激进分子入侵一家家具店以抗议环境问题，但发现自己与一个痴迷于狩猎的夜间警卫困在一起。

4. 战争（2025 年 4 月 11 日）

   • 类型：动作、剧情、战争
   • 描述：根据前海豹突击队队员雷·门多萨在伊拉克战争期间的真实经历改编。

5. 业余爱好者（2025 年 4 月 11 日）

   • 类型：动作、惊悚
   • 描述：一位中央情报局密码学家勒索他的机构训练他去追捕杀害他妻子的恐怖分子。

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 IMDb Server：

npx -y @smithery/cli install @uzaysozen/imdb-mcp-server --client claude

选项 1：使用 Docker（推荐）

1. 克隆此存储库

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

2. 安装依赖项

pip install -r requirements.txt

3. 构建 Docker 镜像

docker build -t imdb_server .

4. 运行 Docker 容器（确保您的 API 密钥作为环境变量传递）

docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

5. 将此添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "imdb_server": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "imdb_server",
        "imdb-mcp-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

选项 2：直接 Python 执行

1. 克隆此存储库

git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server

2. 安装依赖项

pip install -r requirements.txt

3. 设置 API 密钥环境变量

export RAPID_API_KEY_IMDB=your_api_key_here

4. 将此添加到您的 claude_desktop_config.json，根据需要调整 Python 路径：

{
  "mcpServers": {
    "imdb_server": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/imdb_server.py"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

启动服务器

# 直接启动服务器
python imdb_server.py

# 或使用 MCP CLI
mcp run imdb_server.py

# 或者，如果使用 Docker，服务器会自动随容器启动
docker run -d -p 8000:8000 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

添加您选择的配置后，重新启动 Claude Desktop 以加载 IMDb 服务器。然后，您就可以在与 Claude 的对话中使用所有电影和电视节目数据工具。

技术细节

该服务器构建于：

• 通过 RapidAPI 的 IMDb API
• 用于 API 接口的 MCP
• 用于 API 通信的 Requests
• 用于服务器实现的 FastMCP
• 自定义内存缓存系统
• 智能分页，将每个请求的结果限制为 5 个项目，从而优化 AI 代理的使用

分页系统

所有数据检索工具都实现了分页以增强 AI 代理的性能：

目的

• AI 优化响应：将每个响应限制为 5 个项目，防止处理数据的 AI 代理不堪重负
• 重点结果：帮助代理向用户提供更相关和简洁的信息
• 改进的处理：减少 AI 代理在分析电影和电视节目数据时的认知负荷

实施

• 每个分页端点都接受一个 start 参数（默认值：0）
• 结果包括导航元数据（totalCount、hasMore、nextStart）
• 所有集合端点上一致的 5 项页面大小
• 带有分页的示例请求：get_top_250_movies(start=5) 返回项目 6-10

好处

• 更好的代理响应：防止 AI 代理一次接收太多数据
• 可管理的信息：创建代理可以有效处理的可消化数据块
• 顺序访问：允许通过多个工具调用对大型数据集进行结构化探索

缓存系统

该服务器实现了一个高效的缓存系统，以提高性能并减少 API 调用：

特性

• 内存缓存：将 API 响应存储在内存中以进行快速检索
• 可配置的过期时间和大小：缓存条目在可自定义的时间段后过期（默认值：10 分钟），并且具有 100 个缓存键的默认大小
• 自动缓存清理：定期（默认值：5 分钟）删除过期的条目，以使用后台线程管理内存使用情况
• 缓存键：根据 URL 和查询参数生成，以确保唯一性

好处

• 减少 API 使用量：通过重用响应来帮助保持在 API 速率限制内
• 更快的响应时间：消除缓存查询的网络延迟
• 成本效益：最大限度地减少 API 调用次数，尤其是对于热门或重复的查询

配置

可以在代码中调整缓存大小和过期时间：

# 默认值为 600 秒（10 分钟）和 100 个缓存键
response_cache = ResponseCache(expiry_seconds=120, max_size=50)

限制

• API 速率限制根据您的 RapidAPI 订阅而应用
• 一些详细信息可能需要额外的 API 调用
• 搜索结果可能限制为每个请求的特定项目数
• 服务器重新启动时，内存缓存会丢失
• 所有分页响应每页最多返回 5 个项目

故障排除

问题	解决方案
API 密钥未被识别	确保已正确设置 RAPID_API_KEY_IMDB 环境变量
超出速率限制	检查您的 RapidAPI 订阅层级和限制
超时错误	服务器的超时时间为 30 秒；对于大型请求，请尝试限制参数
空结果	尝试更广泛的搜索词，或检查 IMDb 数据库中是否存在该内容
高内存使用率	如果使用许多唯一查询长时间运行，请偶尔重新启动服务器以清除缓存

许可证

此 MCP 服务器在 MIT 许可证下可用。