AI导哈

TMDB电影数据库协议服务器

一个生产就绪的模型上下文协议（MCP）服务器，集成了The Movie Database (TMDB) API，设计用于在Cloudflare Workers上运行，提供全面的电影和电视数据访问功能。

  • by 20Youssef10
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 20Youssef10/tmdb-mcp-server

使用说明

TMDB MCP服务器

一个可用于生产的模型上下文协议（MCP）服务器，与电影数据库（TMDB）API集成，旨在使用Hono.js框架在Cloudflare Workers上运行。

特性

  • 34 MCP工具 用于全面的TMDB API访问
  • 双重运输支持：SSE（传统）和流式HTTP（新标准）
  • Cloudflare缓存 集成以提高性能
  • 稳健的错误处理 带有优雅的错误消息
  • 类型安全 完全支持TypeScript
  • 了解费率限制 具有适当的错误响应

可用工具

搜索与发现

工具 说明
search_movies 使用可选的年份过滤器按标题搜索电影
search_tv_shows 按名称搜索电视节目
search_person 寻找演员、导演和工作人员
discover_movies 使用滤镜进行高级电影发现
discover_tv 使用滤镜进行高级电视节目发现
get_trending 获取热门电影、电视节目或人物

电影详细信息

工具 说明
get_movie_details 获取包括演员和工作人员在内的全面电影细节
get_movie_recommendations 根据电影获得电影推荐
get_similar_movies 获取与特定电影类似的电影
get_movie_videos 获取一部电影的所有视频（预告片、预告片、剪辑）
get_movie_images 获取电影的所有图片（海报、背景、徽标）
get_movie_reviews 获取电影的用户评论

电视节目详情

工具 说明
get_tv_details 获取电视节目的详细信息，包括季节和剧集
get_tv_recommendations 根据节目获取电视节目推荐
get_similar_tv 获取与特定节目类似的电视节目
get_tv_videos 获取电视节目的所有视频
get_tv_images 获取电视节目的所有图像
get_tv_reviews 获取电视节目的用户评论
get_season_details 获取有关电视节目季的详细信息
get_episode_details 获取有关电视节目集的详细信息

人员详细信息

工具 说明
get_person_details 获取人物传记和电影目录
get_person_images 获取一个人的所有个人资料图像

列表和图表

工具 说明
get_now_playing 获取当前在影院播放的电影
get_upcoming 让电影在未来两周内上映
get_popular_movies 获取当前热门电影
get_top_rated_movies 获得有史以来收视率最高的电影
get_latest_movie 获取最近添加的电影
get_airing_today 让电视节目今天播出
get_on_the_air 获取当前正在播放的电视节目
get_popular_tv 获取当前流行的电视节目
get_top_rated_tv 获得有史以来收视率最高的电视节目
get_latest_tv 获取最新添加的电视节目

参考数据

工具 说明
get_movie_certifications 按国家获得电影认证
get_tv_certifications 按国家获得电视节目认证

先决条件

  • Node.js 18+
  • npm或纱线
  • TMDB API密钥 （读取访问令牌）
  • Cloudflare帐户（用于部署）

设置

1.安装依赖项

npm install

2.配置环境变量

创建一个 .dev.vars 本地开发文件：

cp .dev.vars.example .dev.vars

编辑 .dev.vars 并添加您的TMDB API密钥：

TMDB_API_KEY=your_tmdb_api_key_here

3.地方发展

启动开发服务器：

npm run dev

服务器将在以下时间可用 http://localhost:8787

4.测试终点

离线测试套件：

npm test

实时集成测试（要求 TMDB_API_KEY 以及出站访问 api.themoviedb.org):

npm run test:endpoints
npm run test:integration

健康检查：

curl http://localhost:8787/health

列出可用工具：

curl http://localhost:8787/tools

SSE连接（适用于MCP客户端）：

curl -N http://localhost:8787/sse

部署

部署到Cloudflare Workers

  1. 将TMDB API密钥设置为机密：
wrangler secret put TMDB_API_KEY
  1. 部署：
npm run deploy

MCP客户端配置

苏格兰和南方能源公司运输（传统）

配置您的MCP客户端以使用SSE进行连接：

{
  "mcpServers": {
    "tmdb": {
      "url": "http://localhost:8787/sse",
      "transport": "sse"
    }
  }
}

流式HTTP传输（推荐）

更新、更高效的传输协议：

{
  "mcpServers": {
    "tmdb": {
      "url": "http://localhost:8787/mcp",
      "transport": "streamable-http"
    }
  }
}

对于已部署的员工：

{
  "mcpServers": {
    "tmdb": {
      "url": "https://tmdb-mcp-server.<your-subdomain>.workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

可用端点

端点 方法 描述
/health GET 健康检查和服务器信息
/tools GET 列出所有可用工具
/sse GET SSE传输连接（传统）
/message POST SSE传输消息（传统）
/mcp GET/POST/DELETE 流式HTTP传输

工具使用示例

搜索电影

{
  "name": "search_movies",
  "arguments": {
    "query": "The Matrix",
    "year": 1999
  }
}

获取电影详细信息

{
  "name": "get_movie_details",
  "arguments": {
    "movie_id": 603
  }
}

发现电影

{
  "name": "discover_movies",
  "arguments": {
    "genres": "28,12",
    "min_rating": 7.5,
    "sort_by": "popularity.desc"
  }
}

获取趋势

{
  "name": "get_trending",
  "arguments": {
    "media_type": "movie",
    "time_window": "week"
  }
}

项目结构

tmdb-mcp/
├── src/
│   ├── index.ts           # Main server entry point
│   └── lib/
│       ├── tmdb-client.ts # TMDB API client with caching
│       └── mcp-tools.ts   # MCP tool definitions
├── package.json
├── wrangler.toml
├── tsconfig.json
└── .dev.vars.example

API 参考

TMDB客户端

这 TMDBClient 类为TMDB API提供了一个类型安全的包装器：

  • 自动错误处理
  • 速率限制检测（429个响应）
  • Cloudflare缓存集成
  • 图像URL转换

图像URL

工具返回的所有图像路径都使用以下格式转换为完整URL：

https://image.tmdb.org/t/p/w500/{path}

可选尺寸：w92、w154、w185、w342、w500、w780、原装

错误处理

服务器处理各种错误情况：

  • TMDB API错误：返回描述性错误消息
  • 速率限制：返回429并在标头后重试
  • 网络错误：优美的错误消息
  • 无效输入：Zod验证错误

许可证

麻省理工学院

相关 MCP