星战科技xingzhan.cloud
返回市场
IMDB-MCP服务器

IMDB-MCP服务器

作者：uzaysozen5 星标更新：2025-10-26
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

IMDb MCP 服务器

MIT 许可证 Python 3.13 Docker RapidAPI smithery 徽章

在 MseeP 上验证

在 MCP Review 上验证

这是一个使用 IMDb API 服务实现电影和电视节目信息的 Model Context Protocol (MCP) 的 Python 服务器。

目录

概述

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

特性

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

需求

  • Python: 3.13 或更高版本
  • 包管理器: uv（推荐）或 pip
  • RapidAPI 账户: IMDb API 访问所需

配置

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

  1. 在 RapidAPI 创建一个账户

  2. 在 RapidAPI 上订阅 IMDb API

  3. 使用以下方法之一配置 API 密钥：

    方法 1: Smithery 配置（适用于 HTTP 模式）

    • 当通过 Smithery 安装时，通过 Smithery 配置系统提供您的 API 密钥
    • 密钥按请求传递，允许多用户场景

    方法 2: 环境变量（适用于 stdio 模式）

    export 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(start=0)
get_top_box_office_us获取美国票房记录get_top_box_office_us(start= 0)
get_most_popular_movies获取最受欢迎的电影get_most_popular_movies(start=0)

电视剧工具

分页（每页 5 条结果）

工具描述示例
get_top_250_tv_shows获取 IMDb 排名前 250 的电视剧get_top_250_tv_shows(start=0)
get_most_popular_tv_shows获取最受欢迎的电视剧get_most_popular_tv_shows(start=0)

即将上映工具

分页（每页 5 条结果）

工具描述示例
get_upcoming_releases根据国家获取即将上映的电影和电视剧get_upcoming_releases(country_code="US", type="MOVIE", start=0)
get_country_codes_for_upcoming_releases获取可用的国家代码get_country_codes_for_upcoming_releases()

印度亮点工具

分页（每页 5 条结果）

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

示例提示和响应

最近未来将上映的 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日）

    • 类型：动作、惊悚
    • 描述：一名CIA密码学家威胁他的机构训练他去追捕杀害他妻子的恐怖分子。

安装

通过 Smithery 安装（推荐）

要通过 Smithery 自动安装 IMDb 服务器到 Claude Desktop：

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

这将自动通过 Smithery 的配置系统配置服务器并使用您的 RapidAPI 密钥。

方案 1: 使用 Docker

  1. 克隆这个仓库
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server
  1. 构建 Docker 镜像
docker build -t imdb_server .
  1. 运行 Docker 容器
docker run -d -p 8081:8081 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

注意：Docker 容器默认在 HTTP 模式下运行，端口为 8081。

方案 2: 直接使用 Python 执行（使用 uv）

  1. 克隆这个仓库
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server
  1. 安装 uv（如果尚未安装）
# 在 macOS 和 Linux 上
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. 使用 uv 安装依赖项
uv sync
  1. 将以下内容添加到您的 claude_desktop_config.json 中：
{
  "mcpServers": {
    "imdb_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/imdb-mcp-server",
        "run",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

启动服务器

Stdio 模式（默认用于本地开发）

# 使用 uv（推荐）
uv run imdb-server

# 或直接使用 Python 模块
python -m imdb_mcp_server

HTTP 模式（用于 Docker 和 Smithery）

# 使用 uv
TRANSPORT=http uv run imdb-server

# 或使用 Python 模块
TRANSPORT=http python -m imdb_mcp_server

# 使用自定义端口
TRANSPORT=http PORT=8081 uv run imdb-server

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

技术细节

服务器构建于：

  • Python 3.13+: 现代 Python 运行时
  • FastMCP: 支持 HTTP 和 stdio 传输的服务器实现
  • IMDb API 通过 RapidAPI: 主要数据源
  • Requests: API 通信库
  • Smithery: 配置和部署管理
  • uv: 快速的 Python 包管理和运行器
  • 自定义内存缓存系统: 优化响应缓存，采用 LRU 走失策略
  • 智能分页: 每个请求限制结果为 5 个项目，优化 AI 代理消费

传输模式

服务器支持两种传输模式：

  1. Stdio 模式（默认）: 传统的 MCP 服务器通过标准输入/输出进行通信

    • 用于本地 Claude Desktop 安装
    • 通过环境变量 (RAPID_API_KEY_IMDB) 配置

  2. HTTP 模式: 支持 CORS 的 RESTful HTTP 传输

    • 用于 Docker 部署和 Smithery
    • 支持通过 Smithery 配置系统按请求配置
    • 默认运行在端口 8081（可通过 PORT 环境变量配置）

分页系统

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

目的

  • AI 优化响应: 每个响应限制为 5 个项目，防止处理数据的 AI 代理过载
  • 聚焦结果: 帮助代理提供更相关和简洁的信息给用户
  • 改进处理: 减少 AI 代理分析电影和电视剧数据的认知负荷

实现

  • 每个分页端点接受一个 start 参数（默认值：0）
  • 结果包括导航元数据（总数、是否有更多、下一个起始位置）
  • 所有集合端点的一致 5 项页面大小
  • 带分页的示例请求：get_top_250_movies(start=5) 返回第 6 到第 10 项

优点

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

缓存系统

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

功能

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

优点

  • 减少 API 使用: 通过重用响应帮助遵守 API 速率限制
  • 更快的响应时间: 消除缓存查询的网络延迟
  • 成本效益: 最小化 API 调用次数，特别是对于流行或重复的查询

配置

可以在 src/main.py 中调整缓存大小和过期时间：

# 默认值：600 秒（10 分钟）和 100 个缓存键
# 您可以通过修改 ResponseCache 实例化来定制：
response_cache = ResponseCache(max_size=100, expiry_seconds=600)

# 示例使用自定义值：
# response_cache = ResponseCache(max_size=50, expiry_seconds=120)

限制

  • API 速率限制基于您的 RapidAPI 订阅
  • 一些详细信息可能需要额外的 API 调用
  • 搜索结果可能受限于每个请求的项目数量
  • 内存缓存在服务器重启时丢失
  • 所有分页响应每页最多返回 5 个项目

故障排除

问题解决方案
API 密钥未被识别Stdio 模式: 确保 RAPID_API_KEY_IMDB 环境变量正确设置。HTTP 模式: 验证 Smithery 配置中的 rapidApiKeyImdb 是否提供
达到速率限制检查您的 RapidAPI 订阅级别和限制在 RapidAPI 仪表板
超时错误服务器有一个 30 秒超时；对于大请求，尝试限制参数或使用分页
结果为空尝试更广泛的搜索词或检查内容是否存在于 IMDb 数据库中
内存使用过高如果长时间运行且有许多独特查询，请偶尔重启服务器以清除缓存
端口已被占用使用 PORT 环境变量更改端口（仅限 HTTP 模式）: `PORT=8082 python src/main