tmdb-mcp-server

TMDB MCP 服务

一个 Model Context Protocol (MCP) 服务，可访问 The Movie Database (TMDB) API。此服务支持 Claude 和其他 MCP 客户端搜索电影、电视剧和人物，还可获取详细信息与推荐内容。

🌟 现已在 Official MCP Registry 上线

快速开始

使用 npm，几秒即可开始：

# Install globally
npm install -g tmdb-mcp-server

# Or use with npx (no installation needed)
npx tmdb-mcp-server

获取免费的 TMDB API 令牌：https://www.themoviedb.org/settings/api

功能

🎬 电影工具

• search_movies - 按片名搜索电影
• get_movie_details - 获取指定电影的详细信息（预算、票房、时长、类型等）
• discover_movies - 使用高级筛选条件查找电影（类型、语言、年份范围、评分、排序）
• get_recommendations - 根据指定电影获取电影推荐
• get_movie_credits - 获取电影的演职人员信息

📺 电视剧工具

• search_tv_shows - 按名称搜索电视剧
• get_tv_details - 获取指定电视剧的详细信息（季、集、电视网等）
• discover_tv_shows - 使用高级筛选条件查找电视剧（类型、语言、年份、评分、排序）
• get_tv_recommendations - 根据指定电视剧获取电视剧推荐
• get_tv_credits - 获取电视剧的演职人员信息

👥 人物工具

• search_people - 搜索演员、导演及其他娱乐行业从业者
• get_person_details - 获取人物的详细传记信息

🔥 热门趋势

• get_trending - 获取每日或每周热门趋势电影、电视剧或人物

安装

选项 1：npm（推荐）

从 npm 注册表安装：

npm install -g tmdb-mcp-server

就这样！无需构建。

选项 2：从源代码安装（用于开发）

前提条件：

• Node.js（v18 或更高版本）
• TMDB API 访问令牌（可在 TMDB 免费获取）

步骤：

1. 克隆代码库：

git clone https://github.com/tcehjaava/tmdb-mcp-server.git
cd tmdb-mcp-server

2. 安装依赖：

npm install

3. 创建 .env 文件并填入 TMDB 访问令牌：

cp .env.example .env
# Edit .env and add your TMDB_ACCESS_TOKEN

4. 构建服务：

npm run build

使用方法

配合 Claude Desktop 使用

将服务添加到 Claude Desktop 配置中：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

通过 npm 安装时：

{
  "mcpServers": {
    "tmdb": {
      "command": "npx",
      "args": ["-y", "tmdb-mcp-server"],
      "env": {
        "TMDB_ACCESS_TOKEN": "your_tmdb_access_token_here"
      }
    }
  }
}

从源代码安装时：

{
  "mcpServers": {
    "tmdb": {
      "command": "node",
      "args": ["/absolute/path/to/tmdb-mcp-server/build/index.js"],
      "env": {
        "TMDB_ACCESS_TOKEN": "your_tmdb_access_token_here"
      }
    }
  }
}

配合其他 MCP 客户端使用

此服务默认通过 stdio 运行，因此兼容任何支持 stdio 传输的 MCP 客户端。

远程部署（HTTP 模式）

此服务还支持 Streamable HTTP 传输，可用于远程部署：

MCP_TRANSPORT=http PORT=3000 node build/index.js

有关 Railway 等平台的详细部署说明，请参阅 TRANSPORT.md。

开发

本地开发

在监视模式下运行服务以进行开发：

npm run watch

调试

使用 MCP Inspector 进行调试：

npm run inspector

Inspector 提供用于测试和调试 MCP 工具的 Web 界面。

代码格式化

使用 Prettier 格式化代码：

npm run format

示例查询

以下是一些可在 Claude 中尝试的示例查询：

• “查找 2020 年及之后评分高于 7 分的日本科幻电影”
• “本周最热门的电影有哪些？”
• “根据《黑客帝国》给我推荐一些电影”
• “搜索 Christopher Nolan 的电影”
• “显示电视剧《绝命毒师》的详细信息”
• “查找评分较高的韩国剧集”

API 速率限制

TMDB API 的免费套餐有速率限制：

• 每秒 50 个请求
• 建议在生产环境中实现缓存

贡献

欢迎贡献！欢迎提交 Pull Request。对于重大更改，请先创建 issue，讨论您希望进行的更改。

请参阅 CONTRIBUTING.md 了解相关指南。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 使用 Model Context Protocol SDK 构建
• 数据由 The Movie Database (TMDB) 提供
• 本产品使用 TMDB API，但未获得 TMDB 的认可或认证

链接

• MCP 文档
• TMDB API 文档
• Claude Desktop