ČSFD

✨ 機能

• 🎯 型安全 - 型定義を含むTypeScriptの完全サポート
• 🧪 十分なテスト - コードカバレッジは約100%
• 🚀 ユニバーサル - Node.js、ブラウザー、サーバーレス環境で動作
• 🐳 Docker対応 - ビルド済みDockerイメージを利用可能
• 🍺 Homebrewサポート - Homebrew tapを使ってCLIを簡単にグローバルインストール
• 🤖 MCPサーバー - Claude DesktopなどのLLMからCSFDデータを直接利用
• 🔄 モダンなAPI - Promiseベースでasync/awaitをサポート
• 📦 依存関係が少ない - 軽量かつ効率的

対応プラットフォーム

• Node.js（ESMおよびCommonJS）
• ブラウザー（CORSに関する考慮が必要）
• Dockerコンテナー
• macOS/Linux CLI（Homebrew経由）
• MCPサーバー（Claude Desktopなど）
• サーバーレス（Firebase Functions、AWS Lambda、CloudFlare Workersなど）
• Chrome拡張機能
• React Native（Expoにも対応！）

📦 インストール

npm install node-csfd-api
# yarn add node-csfd-api
# pnpm add node-csfd-api

🚀 クイックスタート

import { csfd } from 'node-csfd-api';

// Fetch movie details
const movie = await csfd.movie(535121);
console.log(movie.title); // "Na špatné straně"

// Search for content
const results = await csfd.search('Tarantino');
console.log(results.movies, results.tvSeries, results.users);

// Get creator info
const creator = await csfd.creator(2120);
console.log(creator.name); // "Quentin Tarantino"

// Get user ratings
const ratings = await csfd.userRatings('912');
console.log(ratings);

// Get user reviews
const reviews = await csfd.userReviews('195357-verbal');
console.log(reviews);

📖 目次

• 映画の詳細
• 検索
• クリエイター
• ユーザー評価
• ユーザーレビュー
• 言語とリクエストのオプション
• エラー処理
• ブラウザー認証Cookie
• CLIツール
• MCPサーバー
• Dockerサポート
• REST API
• 開発

📚 APIリファレンス

映画

ČSFD IDを使って、映画やテレビシリーズの詳細情報を取得します。

メソッド： csfd.movie(id: number | string, options?: CSFDOptions): Promise<CSFDMovie>

IDには数値、スラッグ（'535121-na-spatne-strane'）、またはČSFDの完全なURLを指定できます。クリエイターとユーザーにも同じ形式を使用できます。

import { csfd } from 'node-csfd-api';

// Using async/await
const movie = await csfd.movie(535121);

// Alternatively, using promises
csfd.movie(535121).then((movie) => console.log(movie));

{
  id: 535121,
  title: 'Na špatné straně',
  year: '2018',
  descriptions: [
    'Otupělý policejní veterán Ridgeman (Mel Gibson)...',
    'Brett je policajt tesne ...'
  ],
  genres: [ 'Krimi', 'Drama', 'Thriller' ],
  type: 'film',
  url: 'https://www.csfd.cz/film/535121',
  origins: [ 'USA', 'Kanada' ],
  colorRating: 'good',
  rating: 73,
  ratingCount: 6654,
  photo: '//image.pmgstatic.com/cache/resized/w1326/files/images/film/photos/162/980/162980090_bbffbb.jpg',
  trivia: ['Když Henry (Tory Kittles) se svým mladším bratrem...', 'Ve filmu se střídají...'],
  titlesOther: [
    { country: 'USA', title: 'Dragged Across Concrete' },
    { country: 'Kanada', title: 'Dragged Across Concrete' },
    { country: 'Slovensko', title: 'Na zlej strane' },
    { country: 'Austrálie', title: 'Dragged Across Concrete' },
    { country: 'Velká Británie', title: 'Dragged Across Concrete' }
  ],
  poster: 'https://image.pmgstatic.com/cache/resized/w1080/files/images/film/posters/163/579/163579352_bf8737.jpg',
  creators: {
    directors: [
    {
      id: 87470,
      name: 'S. Craig Zahler',
      url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'
      }
    ],
    actors: [
      {
        id: 1,
        name: 'Mel Gibson',
        url: 'https://www.csfd.cz/tvurce/1-mel-gibson/'
      }
    ],
    basedOn: [],
    writers: [
      {
        id: 87470,
        name: 'S. Craig Zahler',
        url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'
      }
    ],
    music: [
      {
        id: 203209,
        name: 'Jeff Herriott',
        url: 'https://www.csfd.cz/tvurce/203209-jeff-herriott/'
      }
    ],
    producers: [
      {
        id: 320006,
        name: 'Sefton Fincham',
        url: 'https://www.csfd.cz/tvurce/320006-sefton-fincham/'
      }
    ]
  },
  vod: [
    {
      title: 'Voyo',
      url: 'https://voyo.nova.cz/filmy/4604-na-spatne-strane'
    },
    {
      title: 'DVD',
      url: 'https://filmy.heureka.cz/na-spatne-strane-dvd/#utm_source=csfd.cz&utm_medium=cooperation&utm_campaign=csfd_movies_feed'
    }
  ],
  tags: ['město', 'sledování'],
  premieres: [
   {
      country: 'Česko',
      format: 'Na Blu-ray',
      date: '07.08.2019',
      company: 'Magic Box'
    },
    {
      country: 'USA',
      format: 'V kinech',
      date: '22.03.2019',
      company: 'Lionsgate US'
    }
  ]
}

検索

ČSFDデータベースから映画、テレビシリーズ、クリエイター、ユーザーを検索します。

メソッド： csfd.search(query: string, options?: CSFDOptions): Promise<CSFDSearch>

import { csfd } from 'node-csfd-api';

const results = await csfd.search('bart');

// Access different result types
console.log(results.movies); // Array of movies
console.log(results.tvSeries); // Array of TV series
console.log(results.users); // Array of users

[
  {
    id: 19653,
    title: 'Black Bart',
    year: '1975',
    url: 'https://www.csfd.cz/film/19653-black-bart/',
    type: 'tv-film',
    colorRating: 'bad',
    poster: 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7',
    origins: ['USA'],
    creators: {
      directors: [{
        id: 87470,
        name: 'S. Craig Zahler',
        url: 'https://www.csfd.cz/tvurce/87470-s-craig-zahler/'
      }],
      actors: [{
        id: 1,
        name: 'Mel Gibson',
        url: 'https://www.csfd.cz/tvurce/1-mel-gibson/'
      }]
    }
  }
],
tvSeries: [
  {
    id: 71924,
    title: 'Království',
    year: 1994,
    url: 'https://www.csfd.cz/film/71924-kralovstvi/',
    type: 'series',
    colorRating: 'good',
    poster: 'https://image.pmgstatic.com/cache/resized/w60h85/files/images/film/posters/166/708/166708064_2da697.jpg',
    origins: ['Dánsko'],
    creators: []
  }
],
users: [
  {
    id: 912,
    user: 'BART!',
    userRealName: 'Lukáš Barták',
    avatar: 'https://image.pmgstatic.com/cache/resized/w45h60/files/images/user/avatars/000/281/281554_1c0fef.jpg',
    url: 'https://www.csfd.cz/uzivatel/912-bart/'
  }
]

クリエイター

クリエイターの経歴やフィルモグラフィーなど、詳細情報を取得します。

メソッド： csfd.creator(id: number | string, options?: CSFDOptions): Promise<CSFDCreator>

import { csfd } from 'node-csfd-api';

const creator = await csfd.creator(2120); // Quentin Tarantino

console.log(creator.name); // Name
console.log(creator.bio); // Biography
console.log(creator.films); // Filmography
console.log(creator.birthday); // Birth date
// ... many more properties, see example

{
  id: 2120,
  name: 'Quentin Tarantino',
  birthday: '27.03.1963',
  birthplace: 'Knoxville, Tennessee, USA',
  photo: 'https://image.pmgstatic.com/cache/resized/w100h132crop/files/images/creator/photos/164/515/164515525_b98f8a.jpg',
  age: 58,
  bio: 'Quentin Tarantino se narodil 27. března roku 1963 v americkém Knoxville teprve šestnáctileté Connie Tarantinové. Své jméno Quentin dostal podle matčiny oblíbené televizní postavy Quinta ze seriálu "Gunsmoke". Quentinův otec byl jistý Tony Tarantino, který rodinu opustil když byl Quentin ještě malinký. Jeho dětství a dospívání ovlivnily nejen filmy, ale pop kultura obecně. Televizní seriály, komiksy, populární hudba, to vše jako mladý hltal ve velkém a stále neměl…',
  films: [
    {
      id: 527699,
      title: 'Tenkrát v Hollywoodu',
      year: 2019,
      colorRating: 'good'
    },
    {
      id: 362228,
      title: 'Osm hrozných',
      year: 2015,
      colorRating: 'good'
    },
    {
      id: 294824,
      title: 'Nespoutaný Django',
      year: 2012,
      colorRating: 'good'
    },
    {
      id: 117077,
      title: 'Hanebný pancharti',
      year: 2009,
      colorRating: 'good'
    },
    {
      id: 229384,
      title: 'Grindhouse: Auto zabiják',
      year: 2007,
      colorRating: 'average'
    },
    {
      id: 178904,
      title: 'Sin City - město hříchu',
      year: 2005,
      colorRating: 'good'
    },
    {
      id: 136304,
      title: 'Kill Bill 2',
      year: 2004,
      colorRating: 'good'
    },
    { id: 43483, title: 'Kill Bill', year: 2003, colorRating: 'good' },
    {
      id: 8850,
      title: 'Jackie Brown',
      year: 1997,
      colorRating: 'good'
    },
    {
      id: 7743,
      title: 'Čtyři pokoje',
      year: 1995,
      colorRating: 'good'
    },
    {
      id: 8852,
      title: 'Pulp Fiction: Historky z podsvětí',
      year: 1994,
      colorRating: 'good'
    }
  ]
}

ユーザー評価

ユーザーのČSFDプロフィールから評価を取得します。

メソッド： csfd.userRatings(user: number | string, config?: CSFDUserRatingConfig, options?: CSFDOptions): Promise<CSFDUserRatings[]>

基本的な使い方

import { csfd } from 'node-csfd-api';

// Latest ratings (first page, ~50 items)
const ratings = await csfd.userRatings('912-bart');

詳細オプション

// Get specific page
const page2 = await csfd.userRatings('912-bart', { page: 2 });

// Get all ratings (use with caution - rate limiting applies)
const allRatings = await csfd.userRatings('912-bart', {
  allPages: true,
  allPagesDelay: 2000 // 2 second delay between requests
});

// Filter by content type
const onlyMovies = await csfd.userRatings('912-bart', {
  includesOnly: ['film']
});

const excludeEpisodes = await csfd.userRatings('912-bart', {
  excludes: ['episode', 'season']
});

⚠️ 配慮してください：allPagesはページごとに1回リクエストを送信します。ČSFDに不要な負荷をかけないよう、リクエストの間隔（allPagesDelay）を空けてください。

[
  {
    id: 812944,
    title: 'David Attenborough: Život na naší planetě',
    year: 2020,
    type: 'film',
    url: 'https://www.csfd.cz/film/812944-david-attenborough-zivot-na-nasi-planete/',
    colorRating: 'good',
    userDate: '2020-11-01',
    userRating: 5
  },
  {
    id: 912552,
    title: 'Coronation',
    year: 2020,
    type: 'film',
    url: 'https://www.csfd.cz/film/912552-coronation/',
    colorRating: 'good',
    userDate: '2020-10-28',
    userRating: 4
  }
];

📝 Note：includesOnly と excludes は相互に排他的です。両方が指定された場合は、includesOnly が優先されます。

🔗 CSFDFilmTypes の定義を参照してください。

ユーザーレビュー

ČSFD プロフィールから詳細なユーザーレビューを取得します。

メソッド： csfd.userReviews(user: number | string, config?: CSFDUserReviewsConfig, options?: CSFDOptions): Promise<CSFDUserReviews[]>

基本的な使い方

import { csfd } from 'node-csfd-api';

// Get latest reviews
const reviews = await csfd.userReviews(195357);

高度なオプション

// Get specific page
const page2 = await csfd.userReviews(195357, { page: 2 });

// Get all reviews with rate limiting
const allReviews = await csfd.userReviews(195357, {
  allPages: true,
  allPagesDelay: 2000
});

// Filter by content type
const filtered = await csfd.userReviews(195357, {
  excludes: ['episode', 'season']
});

[
  {
    id: 1391448,
    title: 'Co s Péťou?',
    year: 2025,
    type: 'film',
    url: 'https://www.csfd.cz/film/1391448-co-s-petou/prehled/',
    colorRating: 'good',
    userDate: '2025-11-27',
    userRating: 4,
    text: 'Co s Péťou? Inu, co by? Každý normální Sparťan by to okamžitě...',
    poster:
      'https://image.pmgstatic.com/cache/resized/w240h339/files/images/film/posters/170/492/170492173_1l3djd.jpg'
  },
  {
    id: 1530416,
    title: 'Kouzlo derby',
    year: 2025,
    type: 'film',
    url: 'https://www.csfd.cz/film/1530416-kouzlo-derby/prehled/',
    colorRating: 'average',
    userDate: '2025-11-26',
    userRating: 1,
    text: 'Typické kolečkoidní sebevykradačské pásmo klišovitých...',
    poster:
      'https://image.pmgstatic.com/cache/resized/w240h339/files/images/film/posters/170/230/170230377_cimu90.jpg'
  }
];

CSFDUserReviewsConfig

CSFDUserRatingConfig と同じオプションです。

言語とリクエストのオプション

すべてのメソッドは、最後の引数として CSFDOptions を受け取ります。

import { csfd } from 'node-csfd-api';

// For a single call
const movie = await csfd.movie(535121, { language: 'en' });
const ratings = await csfd.userRatings(912, { page: 2 }, { language: 'sk' });

// For all subsequent calls
csfd.setOptions({ language: 'en' });

エラー処理

ページを取得できない場合、メソッドは CsfdError を返して拒否されます。reason から理由を確認できます。

import { csfd, CsfdError } from 'node-csfd-api';

try {
  await csfd.movie(999999999);
} catch (error) {
  if (error instanceof CsfdError && error.reason === 'not-found') {
    console.log(`Not found: ${error.url} (HTTP ${error.status})`);
  }
}

ブラウザー認証 Cookie

ČSFD では、訪問者に簡単なブラウザー認証を求めることがあります。このライブラリは認証を自動的に完了し、生成された Cookie を後続のリクエストで再利用します。この Cookie は IP アドレスに紐づき、約 1 週間有効です。そのため、実行間で保持して利用できます。

import { getAnubisCookie, resetAnubisCookie, setAnubisCookie } from 'node-csfd-api';

const cookie = getAnubisCookie(); // Save it, e.g. to a file or a database
setAnubisCookie(cookie); // Restore it on the next start
resetAnubisCookie(); // Forget it and verify again on the next request

💻 CLI ツール

このライブラリには、いくつかのツールを提供する CLI が含まれています。ワークフローに合ったインストール方法を選択してください。

インストール

オプション A：npx (インストール不要)

Node.js から直接実行します。

npx node-csfd-api <command>

オプション B：Homebrew (macOS と Linux)

brew install bartholomej/tap/csfd

オプション C：インストールスクリプト (macOS と Linux)

最新の安定版リリースを、スタンドアロンバイナリとして ~/.local/bin/csfd にインストールします。

curl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | bash
## Install specific version
# curl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | CSFD_VERSION=5.5.0 bash

オプション D：Windows (手動ダウンロード)

最新リリースから csfd-windows-x64.zip をダウンロードし、csfd.exe を展開して PATH に追加してください。

⚠️ バイナリがコード署名されていないため、Windows では SmartScreen の警告（「Windows によって PC が保護されました」）が表示される場合があります。続行するには、詳細情報 → 実行をクリックしてください。または、.exe を右クリック → プロパティ → ブロックの解除にチェックを入れてください。

CLI の使用例

💡 以下の例では csfd（オプション B、C、D）を使用します。npx を使用する場合は、csfd を npx node-csfd-api に置き換えてください。例：npx node-csfd-api export ratings 912

1. 検索

csfd search tarantino
# npx node-csfd-api search tarantino
csfd search "blade runner" --json   # raw JSON output
# npx node-csfd-api search "blade runner" --json

2. 映画の詳細

csfd movie 535121             # by ID
# npx node-csfd-api movie 535121
csfd movie "blade runner"     # by title — searches and shows the top result
# npx node-csfd-api movie "blade runner"
csfd movie 535121 --json      # raw JSON output, pipe-friendly
# npx node-csfd-api movie 535121 --json

3. 評価のエクスポート（CSV、JSON、Letterboxd）

個人のユーザー評価をバックアップします。このツールは、データのローカルコピーを保持する目的でのみ使用してください。

csfd export ratings 912            # CSV (default) -> <userId>-ratings.csv
# npx node-csfd-api export ratings 912
csfd export ratings 912 --json     # JSON -> <userId>-ratings.json
# npx node-csfd-api export ratings 912 --json
csfd export ratings 912 --letterboxd  # Letterboxd CSV -> <userId>-for-letterboxd.csv
# npx node-csfd-api export ratings 912 --letterboxd

3. レビューのエクスポート（CSV、JSON）

csfd export reviews 912            # CSV (default) -> <userId>-reviews.csv
# npx node-csfd-api export reviews 912
csfd export reviews 912 --json     # JSON -> <userId>-reviews.json
# npx node-csfd-api export reviews 912 --json

4. REST API サーバー

csfd server
# npx node-csfd-api server

5. AI エージェント向け MCP サーバー

csfd mcp
# npx node-csfd-api mcp

🤖 MCP サーバー（Model Context Protocol）

このライブラリには、Model Context Protocol（MCP）サーバーが組み込まれています。これにより、Claude Desktop などの LLM 内で ČSFD のデータを直接利用できます。

機能

• 検索：映画、テレビシリーズ、クリエイター、ユーザーを検索します。
• 詳細：映画やクリエイターの包括的な詳細を取得します。
• ユーザー：ユーザーの評価やレビューを読み込みます。

Claude Desktop での使用方法

次の設定を claude_desktop_config.json に追加してください。

{
  "mcpServers": {
    "csfd": {
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"]
    }
  }
}

その他のクライアント

Claude Code

claude mcp add csfd -- npx -y node-csfd-api mcp

Cursor： Claude Desktop と同じ mcpServers 設定を ~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）に追加してください。

VS Code： プロジェクト内の .vscode/mcp.json に次の設定を追加してください。

{
  "servers": {
    "csfd": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"]
    }
  }
}

対応ツール

• search：映画、テレビシリーズ、クリエイター、ユーザーを検索します（ほかのツールで使う ID を返します）
• get_movie：ID を指定して映画またはテレビシリーズの詳細を取得します
• get_creator：ID を指定してクリエイターの詳細とフィルモグラフィーを取得します
• get_user_ratings：ユーザーの評価（ページ単位）
• get_user_reviews：ユーザーのレビュー（ページ単位）
• get_cinemas：映画館の上映時間

すべてのツールは、宣言された出力スキーマを含む構造化データを返すため、クライアントは想定されるフィールドを把握できます。また、俳優またはクリエイターの最も評価の高い映画を見つけてランキングする actor-top-rated プロンプトもあります。

🐳 Docker のサポート

Docker を使用して、CSFD API をスタンドアロンの REST サービスとして実行します。

ビルド済みイメージを使用する

# Pull the latest image
docker pull bartholomej/node-csfd-api

# Run the container
docker run -p 3000:3000 bartholomej/node-csfd-api

独自のイメージをビルドする

# Build the image
docker build -t node-csfd-api .

# Run the container
docker run -p 3000:3000 node-csfd-api

REST API

サーバーをDocker（上記）、csfd server、またはnpx node-csfd-api serverで起動し、http://localhost:3000にアクセスします。

すべてのエンドポイントで?language=cs|en|skを指定できます。ユーザーの評価とレビューでは、page、allPages、allPagesDelay、includesOnly、excludes（カンマ区切り。例：?excludes=episode,season）も指定できます。

設定（環境変数）：

docker run -p 3000:3000 -e API_KEY=my-secret bartholomej/node-csfd-api

エラーは、対応するステータスコードとともにJSON（{ "error": "MOVIE_FETCH_FAILED", "message": "…" }）で返されます。

Docker Hub： bartholomej/node-csfd-api

🌟 実際の利用例

このライブラリは、複数の本番アプリケーションで利用されています。

ブラウザー拡張機能

• Netflix ČSFD Extension - NetflixにČSFDの評価を表示します（ソース）
• Dafilms Extension - DafilmsにČSFDを統合します（ソース）
• Kviff.tv Extension - Kviff.tvにČSFDの評価を表示します（ソース）

Webアプリケーション

• bartweb.cz - Firebase Functionsを使って映画の「最終視聴日時」を記録する個人ウェブサイト

モバイルアプリケーション

• KinoKlub - AeroFilmsの映画館チェーン向けReact Nativeアプリ（AndroidおよびiOS）

🔮 ロードマップ

完了した機能 ✅

• 映画・テレビシリーズ
  • 基本情報（タイトル、年、評価、ポスター、上映時間）
  • 詳細なメタデータ（ジャンル、制作国、VOD プラットフォーム）
  • キャスト・スタッフ（監督、俳優、脚本家、作曲家、プロデューサーなど）
  • 関連コンテンツ（類似作品、トリビア）
  • 別タイトル、公開日、タグ
• 検索
  • 映画、テレビシリーズ、クリエイター、ユーザー
• クリエイター
  • 経歴、フィルモグラフィー
• ユーザーデータ
  • ページネーションとフィルタリングに対応した評価
  • ページネーションとフィルタリングに対応したレビュー

予定されている機能 🚧

• 検索：クリエイターの検索機能
• 映画：映画詳細ページからのレビュー表示
• 映画：オリジナルサウンドトラック（OST）の情報
• サーバー：パフォーマンス向上のためのキャッシュレイヤー
• サーバー：レート制限ヘルパー

🛠️ 開発

プロジェクトをローカルで実行したり、ソースから REST サーバーや MCP サーバーを起動したり、テストを実行したりする方法は、すべてCONTRIBUTING.mdに記載されています。

🤝 コントリビューション

コントリビューションを歓迎します！プルリクエストを作成する前に、CONTRIBUTING.mdをお読みください。

バグを見つけた場合やアイデアがある場合は、イシューを作成してください。

⭐️ サポート

このプロジェクトが役に立ったと感じ、勇気があれば、🍺や🍵のために寄付をご検討ください ;)

• GitHubで⭐️を付ける
• このプロジェクトが役立ちそうな人に共有する
• 継続的な開発を支援するためにプロジェクトをスポンサーする

皆さまのサポートが、このライブラリの維持と改善に役立ちます！🙏

🔒 プライバシーとセキュリティ

このライブラリは、ユーザーデータを収集、保存、送信しません。

すべてのリクエストは、アプリケーションから ČSFD.cz に直接送信されます。仲介サーバーは介さず、このライブラリによってデータが記録または保存されることもありません。

物理的に不可能です。データを保存する場所がありません。保存するためのサーバーデータベースさえありません。ですから、たとえJustin Bieberがあなたのデータを見たいと頼んできても、見せるものは何もありません。

重要な注意事項

• これはスクレイピングライブラリです。責任を持って使用し、❤️ ČSFDの利用規約を尊重してください
• 本番環境では、適切なレート制限を実装してください
• サーバー負荷を最小限に抑えるため、レスポンスのキャッシュをご検討ください
• ブラウザーで使用する場合は、CORS の制限にご注意ください

📝 ライセンス

MIT © 2020 - 2026 Lukas Bartak

詳細については、LICENSEをご覧ください。