MCP Tmdb

🚀 MCP TMDB

本項目是對模型上下文協議（MCP）的一種實現，它提供了與電影數據庫（TMDB）進行交互的工具。

🚀 快速開始

前提條件

• Node.js（推薦版本：18 或更高）
• pnpm（版本 10.7.0 或更高）

安裝步驟

1. 克隆倉庫：

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

2. 安裝依賴：

pnpm install

3. 在項目根目錄創建一個 .env 文件，並填入你的 TMDB API 密鑰：

TMDB_API_KEY=your_api_key_here

運行項目

要運行 MCP 服務器：

pnpm inspector

要以調試模式運行：

pnpm dev:debug

✨ 主要特性

本項目提供了一系列與 TMDB 交互的工具，可用於查詢電影和電視劇相關信息，具體功能如下：

• two_actors_on_screen：搜索兩位演員共同出演的電影。
• two_people：搜索兩人在任意角色下合作的電影。
• two_movies：搜索在兩部電影中擔任任意角色的人員。
• filmography_actor_genre：搜索某位演員在特定類型電影中的作品。
• filmography_crew_genre：搜索某位工作人員在特定類型電影中的作品。
• jobs_list：提供可用於 filmography_crew_genre 工具的可用工作列表。

📦 安裝指南

克隆倉庫

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

安裝依賴

pnpm install

配置環境變量

在項目根目錄創建一個 .env 文件，並填入你的 TMDB API 密鑰：

TMDB_API_KEY=your_api_key_here

💻 使用示例

基礎用法

要運行 MCP 服務器：

pnpm inspector

要以調試模式運行：

pnpm dev:debug

高級用法

不同工具的使用示例如下：

two_actors_on_screen

搜索 Cary Grant 和 Katharine Hepburn 共同出演的電影：

[
    {
        "id": 31866,
        "title": "Sylvia Scarlett",
        "year": 1935,
        "media_type": "movie"
    },
    {
        "id": 900,
        "title": "Bringing Up Baby",
        "year": 1938,
        "media_type": "movie"
    },
    {
        "id": 16274,
        "title": "Holiday",
        "year": 1938,
        "media_type": "movie"
    },
    {
        "id": 981,
        "title": "The Philadelphia Story",
        "year": 1940,
        "media_type": "movie"
    }
]

two_people

搜索 Christopher Nolan 和 Hans Zimmer 合作的電影：

[	
    {
        "id": 272,
        "title": "Batman Begins",
        "year": 2005,
        "media_type": "movie"
    },
    {
        "id": 155,
        "title": "The Dark Knight",
        "year": 2008,
        "media_type": "movie"
    },
    {
        "id": 27205,
        "title": "Inception",
        "year": 2010,
        "media_type": "movie"
    }
 	...
]

two_movies

搜索在《泰坦尼克號》和《指環王：王者歸來》中工作的人員：

[{
        "id": 1369,
        "name": "Bernard Hill",
        "known_for_department": "Acting"
    },
    {
        "id": 1327030,
        "name": "Lora Hirschberg",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    },
    {
        "id": 900,
        "name": "Christopher Boyes",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    },
    {
        "id": 1378696,
        "name": "Ethan Van der Ryn",
        "job": "Sound Effects Editor",
        "known_for_department": "Sound"
    },
    {
        "id": 1425978,
        "name": "Gary Summers",
        "job": "Sound Re-Recording Mixer",
        "known_for_department": "Sound"
    }
]

filmography_actor_genre

搜索 Tom Hanks 的恐怖電影作品：

[{
        "title": "He Knows You're Alone",
        "character": "Elliot",
        "media_type": "movie",
        "year": 1980
    },
    {
        "title": "The 'Burbs",
        "character": "Ray Peterson",
        "media_type": "movie",
        "year": 1989
    },
    {
        "title": "Vault of Horror I",
        "character": "Baxter",
        "media_type": "movie",
        "year": 1994
    }
]

filmography_crew_genre

搜索 Steven Spielberg 作為導演的喜劇電影作品：

[{
        "title": "The Sugarland Express",
        "media_type": "movie",
        "year": 1974,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "1941",
        "media_type": "movie",
        "year": 1979,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "Amazing Stories",
        "media_type": "tv",
        "year": 1985,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "Hook",
        "media_type": "movie",
        "year": 1991,
        "jobs": [
            "Director"
        ]
    },
    {
        "title": "The Terminal",
        "media_type": "movie",
        "year": 2004,
        "jobs": [
            "Director"
        ]
    }
]

jobs_list

獲取可用工作列表：

{
  "jobs": [
    "Director",
    "Producer",
    "Screenplay",
    "Director of Photography",
    "Editor",
    "Production Design",
    "Art Direction",
    "Set Decoration",
    "Costume Design",
    "Makeup",
    "Sound",
    "Visual Effects",
    "Original Music Composer"
  ]
}

📚 詳細文檔

關於 TMDB

The Movie Database (TMDB) 是一個受歡迎的、用戶可編輯的電影和電視劇數據庫。它提供了一個全面的 API，允許開發者訪問電影和電視劇數據，包括：

• 電影和電視劇信息
• 演員和工作人員詳情
• 圖片和海報
• 評分和評論
• 相似內容推薦
• 等等

API 概述

TMDB API 可以免費使用，但需要一個 API 密鑰。你可以通過以下步驟獲取 API 密鑰：

1. 在 TMDB 創建一個賬戶。
2. 進入你的賬戶設置。
3. 選擇“API”部分。
4. 請求一個 API 密鑰。

速率限制

API 有以下速率限制：

• 每 10 秒 40 個請求
• 每天 1000 個請求

有關 API 的更多信息，請訪問 TMDB API 文檔。

MCP 配置

Claude Desktop

要在 Claude Desktop 中配置此 MCP：

1. 打開 Claude Desktop。
2. 轉到設置 > MCP 配置。
3. 添加一個新的 MCP，並使用以下設置：

    "tmdb": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "tsx",
      "args": [
        "complete_path_to_mcp-tmdb\\main.ts"
      ],
      "env": {
        "TMDB_API_KEY": "your_api_key_here"
      }
    }

🔧 技術細節

項目結構

mcp-tmdb/
├── API/              # API 函數和實用工具
├── interfaces/       # 類型和接口定義
├── tools/           # 工具實現
├── main.ts          # 主入口點
├── package.json     # 項目配置
└── .env            # 環境變量（需創建）

主要依賴

• @modelcontextprotocol/sdk: ^1.12.1
• dotenv: ^16.5.0
• zod: ^3.25.55

📄 許可證

本項目採用 MIT 許可證。