IMDb MCP Server

IMDb MCP 服务

已通过 MCP Review 验证

这是一个使用 IMDb API 服务，为电影和电视剧信息实现模型上下文协议（MCP）的 Python 服务。

目录

• 概述
• 功能
• 要求
• 配置
• 工具
  • 搜索工具
  • IMDb ID 工具
  • 配置工具
  • 电影工具
  • 电视剧工具
  • 即将上映内容工具
  • 印度焦点内容工具
• 提示词和响应示例
• 安装
• 启动服务
• 技术详情
  • 传输模式
  • 分页系统
  • 缓存系统
• 限制
• 故障排除
• 许可证

概述

此服务提供一套全面的工具，可通过 IMDb API 访问 IMDb 数据。它充当 Agent 与 IMDb 数据库之间的桥梁，提供有关电影、电视剧、演员、导演等的详细信息。

功能

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

要求

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

配置

此服务需要你自行从 RapidAPI 获取 IMDb API 服务的 API 密钥：

1. 在 RapidAPI 上创建账户
2. 在 RapidAPI 上订阅 IMDb API（提供免费套餐）
3. 从 RapidAPI 控制面板复制 API 密钥
4. 通过 RAPID_API_KEY_IMDB 环境变量提供密钥，可根据你的环境选择以下任一方式：
   • MCP 客户端配置 — 在 env 块中设置（参见安装）。这是常用方式。
   • Shell：export RAPID_API_KEY_IMDB=your_api_key_here
   • .env 文件：将 .env.example 复制为 .env，然后使用 uv run --env-file .env imdb-server 运行
   • HTTP / Docker：向容器传入 -e RAPID_API_KEY_IMDB=...

只有在实际调用工具时才需要密钥；没有密钥，服务仍可启动并列出其工具。

工具

搜索工具

工具	描述	示例
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. A Minecraft Movie（2025 年 4 月 4 日）

   • 类型：动作、冒险、喜剧
   • 简介：四个格格不入的人被传送门带入一个方块构成的奇幻世界，他们与一位技艺高超的工匠踏上旅程，寻找回家的路。

2. Freaky Tales（2025 年 4 月 4 日）

   • 类型：动作、冒险、喜剧
   • 简介：四个相互关联的故事发生在 1987 年的加利福尼亚州奥克兰，讲述了对音乐、电影、人们、地方和回忆的热爱。

3. Wake Up（2025 年 4 月 4 日）

   • 类型：动作、恐怖
   • 简介：年轻的活动人士闯入一家家具店，抗议环境问题，却发现自己被困在里面，与一名沉迷狩猎的夜班保安共处。

4. Warfare（2025 年 4 月 11 日）

   • 类型：动作、剧情、战争
   • 简介：改编自前海豹突击队成员 Ray Mendoza 在伊拉克战争期间的真实经历。

5. The Amateur（2025 年 4 月 11 日）

   • 类型：动作、惊悚
   • 简介：一名 CIA 密码专家胁迫自己的机构对他进行训练，让他追捕杀害妻子的恐怖分子。

安装

这是一个独立的 MCP 服务，可在本地运行，并使用你自己的 RapidAPI 密钥。 Smithery 不再提供免费的托管服务，因此没有共享的远程服务实例——克隆该服务（或使用 uvx），并将 MCP 客户端指向它。

选项 1：使用 uvx 运行（无需克隆）

如果已安装 uv，请将以下内容添加到 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "imdb_server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uzaysozen/imdb-mcp-server",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

选项 2：克隆并使用 uv 运行

1. 安装 uv：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 克隆此仓库并安装依赖项：

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

3. 将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "imdb_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/imdb-mcp-server",
        "run",
        "imdb-server"
      ],
      "env": {
        "RAPID_API_KEY_IMDB": "your_api_key_here"
      }
    }
  }
}

选项 3：通过 HTTP 自托管（Docker）

如需一个共享且始终运行的远程服务，请在 HTTP 模式下运行它，并置于你自己的 HTTPS 端点之后。此操作为可选项，只有在多个客户端需要连接到同一个实例时才需要。

1. 克隆此仓库

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

2. 构建并运行 Docker 镜像

docker build -t imdb_server .
docker run -d -p 8081:8081 -e RAPID_API_KEY_IMDB=your_api_key_here --name imdb_server imdb_server

容器以 HTTP 模式运行，端口为 8081，并在 /mcp 提供 MCP 端点。将其置于负责终止 TLS 的反向代理或平台之后。如果希望将其列在 Smithery 上，请在 smithery.ai/new 将你的公开 https://.../mcp URL 注册为外部服务。

启动服务

Stdio 模式（本地开发的默认模式）

# Using uv (recommended)
uv run imdb-server

# Or directly with Python module
python -m imdb_mcp_server

HTTP 模式（用于自托管）

# Using uv
TRANSPORT=http uv run imdb-server

# Or with Python module
TRANSPORT=http python -m imdb_mcp_server

# With custom port
TRANSPORT=http PORT=8081 uv run imdb-server

添加所选配置后，重启 MCP 客户端（例如 Claude Desktop），以加载 IMDb 服务。之后，你就可以在对话中使用所有电影和电视节目数据工具。

技术详情

此服务基于以下技术构建：

• Python 3.13+：现代 Python 运行时
• MCP Python SDK 2.x（mcp.server.mcpserver.MCPServer）：stdio 和 Streamable HTTP 传输
• 通过 RapidAPI 使用 IMDb API：主要数据源
• Requests：API 通信库
• uv：快速的 Python 包管理器和运行器
• 自定义内存缓存系统：通过 LRU 淘汰机制优化响应缓存
• 智能分页：每次请求最多返回 5 个条目，优化 AI Agent 的使用体验

传输模式

服务器支持两种传输模式，由 TRANSPORT 环境变量选择：

1. Stdio 模式（未设置 TRANSPORT — 默认）：通过标准输入/输出进行 MCP 通信

   • 用于本地 MCP 客户端（Claude Desktop、Claude Code、Cursor 等）
   • API 密钥来自 RAPID_API_KEY_IMDB 环境变量

2. HTTP 模式（TRANSPORT=http）：可流式传输的 HTTP 传输

   • 用于自托管共享实例（Docker，或任何可运行容器的平台）
   • 在 /mcp 提供 MCP 端点
   • 单租户：API 密钥来自服务器上的 RAPID_API_KEY_IMDB
   • 默认绑定到 0.0.0.0:8081（HOST / PORT 环境变量）；请在会终止 TLS 的代理后运行

分页系统

所有数据检索工具都实现了分页，以提升 AI Agent 的性能：

目的

• 针对 AI 优化的响应：将每次响应限制为 5 个条目，避免处理数据的 AI Agent 不堪重负
• 聚焦结果：帮助 Agent 向用户提供更相关、更简洁的信息
• 提升处理效率：降低 AI Agent 分析电影和电视节目数据时的认知负担

实现方式

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

优势

• 更好的 Agent 响应：避免 AI Agent 一次接收过多数据
• 易于处理的信息：将数据拆分为易于理解的块，方便 Agent 有效处理
• 顺序访问：通过多次工具调用，按结构化方式探索大型数据集

缓存系统

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

功能

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

优势

• 减少 API 使用量：重复使用响应，有助于遵守 API 速率限制
• 更快的响应时间：缓存查询无需经历网络延迟
• 提高成本效益：尽可能减少 API 调用次数，尤其是对于热门或重复查询

配置

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

# Defaults: 600 seconds (10 minutes) and 100 cache keys
# You can customize by modifying the ResponseCache instantiation:
response_cache = ResponseCache(max_size=100, expiry_seconds=600)

# Example with custom values:
# response_cache = ResponseCache(max_size=50, expiry_seconds=120)

限制

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

故障排除

问题	解决方案
无法识别 API 密钥	确保已设置 RAPID_API_KEY_IMDB——可在 MCP 客户端配置的 env 块中、Shell、.env 文件中设置，或通过 Docker 容器的 -e 参数设置
ModuleNotFoundError: No module named 'mcp.server.fastmcp'	你使用的是安装了 mcp 2.x 的旧版代码库。拉取最新版本（此服务面向 mcp 2.x / MCPServer），然后运行 uv sync
IMDb API 返回 HTTP 401 / HTTP 403	你的 RapidAPI 密钥无效，或未订阅 IMDb API。请在 RapidAPI 上订阅 IMDb API，然后复制新密钥
IMDb API 返回 HTTP 404	RapidAPI 订阅已失效，或上游端点已更改。请在 RapidAPI 控制面板中检查订阅状态
旧版 npx @smithery/cli install 命令失败	Smithery 已于 2026 年 3 月结束免费托管服务，因此没有共享的远程实例。请改为本地安装——参见安装
超出速率限制	请在 RapidAPI 控制面板中查看 RapidAPI 订阅级别和限制
超时错误	此服务的超时时间为 30 秒；对于大型请求，请尝试限制参数或使用分页
结果为空	尝试使用范围更广的搜索词，或检查 IMDb 数据库中是否存在相关内容
内存占用较高	如果长时间运行且处理了许多不同的查询，请偶尔重启服务以清除缓存
端口已被占用	使用 PORT 环境变量更改端口（仅限 HTTP 模式）：TRANSPORT=http PORT=8082 uv run imdb-server
导入错误	确保已安装所有依赖项：uv sync（或 pip install "mcp[cli]>=2.1,<3" requests）
连接被拒绝（Docker）	确保容器正在运行：docker ps，并检查日志：docker logs imdb_server

许可证

此 MCP 服务采用 MIT 许可证。