IMDb MCP 服务器
一个使用IMDb API服务的Python服务器，用于实现电影和电视节目信息的模型上下文协议（MCP）。
目录
- 搜索工具 - IMDb ID 工具 - 配置工具 - 电影工具 - 电视节目工具 - 即将发布的工具 - 印度聚光灯工具
概述
这个服务器通过IMDb API提供了一套全面的工具，用于访问IMDb数据。它充当代理与IMDb数据库之间的桥梁，提供关于电影、电视节目、演员、导演等的详细信息。
特点/特性
- 🎬 电影和电视节目搜索功能
- 📋 电影和电视剧的详细信息
- 👨👩👧👦 演员及剧组人员信息
- 🏆 评分最高且备受欢迎的内容列表
- 💰 票房数据
- 🌍 针对特定国家的电影信息（特别关注印度电影）
- 🔜 即将发布
- 🔄 高效的响应缓存系统
要求
- python3.13或更高
- 包管理器：使用uv（推荐）或pip
- RapidAPI 账户访问IMDb API所需
配置
此服务器需要RapidAPI提供的IMDb API服务的API密钥：
- 在（某网站/平台）上创建一个账户 RapidAPI（快速API）
- 订阅 IMDb API 在RapidAPI上
- 使用以下方法之一配置API密钥：
方法1：Smithery配置（适用于HTTP模式）
- 当通过Smithery安装时，请通过Smithery配置系统提供您的API密钥 - 关键在于每次请求都会传递密钥，从而支持多用户场景
方法2：环境变量（适用于stdio模式）
export RAPID_API_KEY_IMDB=your_api_key_here工具
搜索工具
| 工具 | 描述 | 示例 | |||
|---|---|---|---|---|---|
| ------ | ------------- | --------- | ** | ** 搜索IMDb search_imdb(primary_title="Inception") | 使用各种筛选选项搜索电影和电视节目 |
|
IMDb ID 工具 | 工具 | 描述 | 示例 | |------|-------------|---------| | 获取IMDb详情 get_imdb_details(imdb_id="tt1375666") | 获取电影或电视节目的详细信息 | | | 获取导演信息 get_directors(imdb_id="tt1375666") | 获取电影的导演信息 | | | 获取演员阵容 get_cast(imdb_id="tt1375666") | 获取电影的演员阵容 | | | 获取作者 get_writers(imdb_id="tt1375666") | 获取电影的编剧 |
|
配置工具 | 工具 | 描述 | 示例 | |------|-------------|---------| | 获取类型 get_types() | 获取所有可用的内容类型 | | | 获取类型（或流派） get_genres() | 获取所有可用的类型 | | | 获取国家列表 get_countries() | 获取所有可用国家 | | | 获取语言列表 get_languages() | 获取所有可用语言 |
|
*电影工具*
分页显示（每页5条结果） | 工具 | 描述 | 示例 | |------|-------------|---------| | 分隔符 | 标题 | 内容 | | get_top_250_movies(start=0) 获取前250部电影 | 从IMDb获取前250部电影 | | | get_top_box_office_us(start=0) 获取美国票房冠军 | 获取美国票房纪录 | | | get_most_popular_movies(start=0) 获取最受欢迎的电影
| 获取最受欢迎的电影 |
*|*
电视节目工具 分页显示（每页5条结果） | 工具 | 描述 | 示例 | |------|-------------|---------| |（无对应中文）|（无对应中文）|（无对应中文）| get_top_250_tv_shows(start=0) | 获取前250名电视节目 | 从IMDb获取排名前250的电视剧 | | get_most_popular_tv_shows(start=0) |
获取最受欢迎的电视节目
*| 获取最受欢迎的电视节目 |*
| 即将发布的工具 分页显示（每页5个结果） | 工具 | 描述 | 示例 | |------|-------------|---------| get_upcoming_releases(country_code="US", type="MOVIE", start=0) | 获取即将发布的版本 | 获取各国即将上映的电影和电视剧信息 | | get_country_codes_for_upcoming_releases() |
获取即将发布版本的国家代码
*| 获取即将发布版本的可用国家代码 |*
| 印度聚光灯工具 分页显示（每页5个结果） | 工具 | 描述 | 示例 | |------|-------------|---------| get_top_rated_malayalam_movies(start=0) | 获取评分最高的马拉雅拉姆语电影 | 获取评分最高的50部马拉雅拉姆语电影 | | get_upcoming_indian_movies(start=0) | 获取即将上映的印度电影 | 获取最受期待的即将上映的印度电影 | | get_trending_tamil_movies(start=0) | 获取热门泰米尔电影 | 获取热门泰米尔电影 | | get_trending_telugu_movies(start=0) | 获取热门泰卢固语电影 | 获取热门泰卢固语电影 | | get_top_rated_tamil_movies(start=0) | 获取评分最高的泰米尔语电影 | 获取评分最高的50部泰米尔电影 | | get_top_rated_telugu_movies(start=0) | 获取评分最高的泰卢固语电影 | 获取评分最高的50部泰卢固语电影 | | get_top_rated_indian_movies(start=0) |
获取评分最高的印度电影
| 获取评分前250名的印度电影 |
|
示例提示与响应 get_upcoming_releases
最近未来将上映的五部动作电影是什么？
我会为你找到即将上映的动作电影。 get_upcoming_releases
称为MCP工具
- 现在我将从这些即将上映的影片中寻找动作片： 称为MCP工具
- 根据搜索结果，以下是即将上映的5部动作电影： - 《我的世界》电影
- （2025年4月4日） 类型：动作、冒险、喜剧
- 描述：四个不合群的家伙被一道传送门带入了一个立方体的奇幻世界，并与一位工艺大师一同踏上归家之旅。 - 怪异故事
- （2025年4月4日） 类型：动作、冒险、喜剧
- 描述：四个相互交织的故事，发生在1987年的加利福尼亚州奥克兰，讲述了对音乐、电影、人、地方和回忆的热爱。 - 醒来
- （2025年4月4日） 类型：动作，恐怖
- 描述：年轻活动分子闯入一家家具店抗议环境问题，却发现自己被困在了一位痴迷狩猎的夜班保安手中。 - 战争
- （2025年4月11日） 类型：动作、剧情、战争
- 描述：根据前海军陆战队成员雷·门多萨在伊拉克战争期间的真实经历改编。 - 《业余爱好者》
（2025年4月11日）
类型：动作、惊悚
描述：一名中央情报局密码学家威胁要曝光其机构，迫使该机构训练他去追捕杀害他妻子的恐怖分子。 安装通过Smithery安装（推荐）
npx -y @smithery/cli install @uzaysozen/imdb-mcp-server --client claude通过自动方式为Claude Desktop安装IMDb服务器
Smithery（根据上下文，可译为“铁匠铺”或“锻造工坊”，具体取决于该词在特定语境中的含义）
- ：
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server- 这将通过Smithery的配置系统自动使用您的RapidAPI密钥配置服务器。
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镜像
- 运行Docker容器
git clone https://github.com/uzaysozen/imdb-mcp-server.git
cd imdb-mcp-server- 注：Docker 容器默认在 8081 端口以 HTTP 模式运行。
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"- 选项2：直接执行Python（使用uv）
uv sync- 克隆此仓库
claude_desktop_config.json如果尚未安装，请安装 uv
{
"mcpServers": {
"imdb_server": {
"command": "uv",
"args": [
"--directory",
"/path/to/imdb-mcp-server",
"run",
"imdb-server"
],
"env": {
"RAPID_API_KEY_IMDB": "your_api_key_here"
}
}
}
}使用 uv 安装依赖项
把这个加到你的（清单/计划/东西里）
# Using uv (recommended)
uv run imdb-server
# Or directly with Python module
python -m imdb_mcp_server:
# 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启动服务器
标准I/O模式（本地开发的默认模式）
HTTP 模式（由 Docker 和 Smithery 使用）
- 添加您选择的配置后，重启Claude桌面应用以加载IMDb服务器。之后，您就可以在与Claude的对话中使用所有电影和电视节目数据工具了。技术细节
- 服务器基于：Python 3.13+
- 现代Python运行时FastMCP
- 支持HTTP和stdio传输的服务器实现通过RapidAPI访问IMDb API
- 主要数据来源请求：
- API通信库Smithery（注：此词在英语中并不常见，可能是Smith的某种变体或特定语境下的用词，直接翻译为中文可能无确切对应词汇，但可理解为与“Smith”相关的某种概念或事物，如“史密斯工艺”等，具体需根据上下文确定）
- 配置与部署管理紫外线
- 快速的Python包管理器和运行器自定义内存缓存系统
使用LRU（最近最少使用）淘汰算法优化响应缓存
智能分页
- 每次请求的结果限制为5个项目，以优化AI代理的使用效率 运输方式
- 服务器支持两种传输模式： - 标准输入输出模式RAPID_API_KEY_IMDB(默认): 通过标准输入/输出进行传统MCP服务器通信
- 用于本地Claude Desktop安装通过环境变量进行配置（
- ） - HTTP 模式 - 支持CORS的RESTful HTTP传输 PORT 用于Docker部署和Smithery（或根据具体上下文，可译为“用于Docker部署及Smithery平台”）
支持通过Smithery配置系统进行每次请求的配置
默认情况下在8081端口运行（可通过配置调整）
环境变量
- 分页系统所有数据检索工具都实现了分页功能，以提升AI代理的性能：
- 目的AI优化的回复
- 将每个响应限制为5个项目，以防止处理数据的人工智能代理因信息过载而受到影响聚焦成果
帮助代理向用户提供更相关、更简洁的信息
- 改进后的处理
start减轻人工智能代理在分析电影和电视节目数据时的认知负担 - 实施
- 每个分页端点都接受一个
- 参数（默认：0）
get_top_250_movies(start=5)结果包括导航元数据（totalCount，hasMore，nextStart）
所有集合端点处保持一致的5项页面大小
- 带有分页功能的请求示例：返回第6到第10项
- 好处；利益更佳的代理回应
- 防止AI代理一次性接收过多数据可管理的信息
生成易于消化的数据块，以便代理能够有效处理
顺序访问
允许通过多次工具调用对大型数据集进行结构化探索
- 缓存系统服务器实现了一个高效的缓存系统，以提高性能并减少API调用：
- 特点/功能内存缓存
- 将API响应存储在内存中以便快速检索可配置的过期时间和大小
- 缓存条目在自定义的时间段（默认：10分钟）后过期，并且默认大小为100个缓存键自动缓存清理
定期（默认：5分钟）使用后台线程移除过期条目以管理内存使用
- 缓存键基于URL和查询参数生成，以确保唯一性
- 好处；利益减少API使用
- 通过重用响应来帮助保持在API速率限制内更快的响应时间
消除缓存查询的网络延迟
成本效益 src/main.py减少API调用的次数，尤其是对于热门或重复的查询
# 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)配置
- 缓存大小和过期时间可以进行调整
- ：
- 局限性
- 根据您的RapidAPI订阅，API速率限制将适用
- 一些详细信息可能需要额外的API调用
每次搜索的结果可能限制为一定数量的条目
服务器重启时，内存缓存会丢失 所有分页响应每页最多返回5个项目 故障排除 | 问题 | 解决方案 ||---------|----------| RAPID_API_KEY_IMDB API密钥未被识别 标准输入输出模式确保 rapidApiKeyImdb 环境变量已正确设置。 HTTP模式 验证 在Smithery配置中提供 | 超出速率限制 | 请检查您的RapidAPI订阅级别和限制，详情请访问 RapidAPI 控制面板 | | 超时错误 | 服务器有30秒的超时限制；对于大型请求，请尝试限制参数或使用分页功能 | PORT | 未找到结果 | 请尝试使用更宽泛的搜索词，或检查内容是否存在于IMDb数据库中 | PORT=8082 python src/main.py | 内存使用过高 | 如果长时间运行且存在大量唯一查询，偶尔重启服务器以清除缓存 | | 端口已被使用 | 使用以下方法更改端口 uv sync 环境变量（仅限HTTP模式）： pip install mcp[cli] requests smithery | | 导入错误 | 确保所有依赖项都已安装： docker ps 或者 docker logs imdb_server |
| 连接被拒绝（Docker）| 确保容器正在运行：
并检查日志：