moviefinder-mcp

一个封装了 The Movie Database (TMDB) API 的 MCP 服务器。使用 @modelcontextprotocol/sdk 和 stdio 传输构建。

工具

所有工具均返回摘要后的 JSON（ID、标题、年份、概述、评分、海报 URL 等）——已剔除冗余的原始 TMDB 字段。

设置

1. 获取 TMDB API 令牌

1. 在 https://www.themoviedb.org/ 注册一个免费账户。

2. 访问 https://www.themoviedb.org/settings/api 并复制 API Read Access Token (v4)。这是一个很长的 JWT —— 不是 v3 API 密钥。

2. 安装与构建

npm install
npm run build

3. 配置环境变量

将 .env.example 复制为 .env 并粘贴您的令牌：

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. 运行服务器

npm start

该服务器通过 stdio 进行 MCP 通信，旨在由 MCP 客户端（如 Claude Desktop）启动，而非交互式运行。

在 Claude Desktop 中注册

在 claude_desktop_config.json 中添加条目：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

编辑配置后重启 Claude Desktop。之后 moviefinder 工具将出现在任何对话中。

脚本

错误处理

服务器针对常见的 TMDB 故障返回有用的消息：

• 401 — 令牌缺失或密钥类型错误（必须是 v4 读取访问令牌）。

• 404 — 请求的电影/资源不存在。

• 429 — 速率限制；如果存在，将包含 Retry-After 值。

注意事项

• 流派列表从 /genre/movie/list 获取一次并缓存在内存中。

• 海报 URL 使用 https://image.tmdb.org/t/p/w500。

• 无数据库，无日志框架 —— 这是设计使然。