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を使用します。

• データベースやログフレームワークは使用していません（設計上の仕様です）。