{ 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' } ] } ``` ### Search > Search for movies, TV series, and users across the ČSFD database. **Method:** `csfd.search(query: string): Promise` ```typescript 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 ```

🔎 Click here to see full result example

```javascript [ { 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/' } ] ```

### Creators > Get detailed information about a creator including their biography and filmography. **Method:** `csfd.creator(id: number): Promise` ```typescript 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 ```

🔎 Click here to see full result example

```javascript { 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' } ] } ```

### User Ratings > Retrieve user ratings from their ČSFD profile. **Method:** `csfd.userRatings(username: string, options?: UserRatingsOptions): Promise` #### Basic Usage ```typescript import { csfd } from 'node-csfd-api'; // Get last page of ratings (~50 items) const ratings = await csfd.userRatings('912-bart'); ``` #### Advanced Options ```typescript // 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', { exclude: ['episode', 'season'] }); ``` > ⚠️ **Rate Limiting Warning**: When fetching all pages, use appropriate delays to avoid detection. Consider implementing exponential backoff for large datasets.

🔎 Click here to see full result example

```javascript [ { 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: '01.11.2020', userRating: 5 }, { title: 'Coronation', year: 2020, type: 'film', url: 'https://www.csfd.cz/film/912552-coronation/', colorRating: 'good', userDate: '28.10.2020', userRating: 4 } ]; ```

#### UserRatingsOptions | Option | Type | Default | Description | | --------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------- | | `includesOnly` | `CSFDFilmTypes[]` | `null` | Include only specific content types (e.g., `['film', 'series']`) | | `exclude` | `CSFDFilmTypes[]` | `null` | Exclude specific content types (e.g., `['episode']`) | | `allPages` | `boolean` | `false` | Fetch all pages of ratings | | `allPagesDelay` | `number` | `0` | Delay between page requests in milliseconds | | `page` | `number` | `1` | Fetch specific page number | | `onProgress` | `(page: number, total: number) => void` | `undefined` | Called on each page fetch — use for progress bars or logging | > 📝 **Note**: `includesOnly` and `exclude` are mutually exclusive. If both are provided, `includesOnly` takes precedence. > > 🔗 See [CSFDFilmTypes definition](https://github.com/bartholomej/node-csfd-api/blob/master/src/dto/global.ts) ### User Reviews > Retrieve detailed user reviews from their ČSFD profile. **Method:** `csfd.userReviews(userId: number | string, options?: UserReviewsOptions): Promise` #### Basic Usage ```typescript import { csfd } from 'node-csfd-api'; // Get latest reviews const reviews = await csfd.userReviews(195357); ``` #### Advanced Options ```typescript // 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, { includesOnly: ['film'], exclude: ['episode'] }); ```

🔎 Click here to see full result example

```javascript [ { 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: '27.11.2025', userRating: 4, text: 'Co s Péťou? Inu, co by? Každý normální Sparťan by to okamžitě mrdnul z útesu...', 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: '26.11.2025', 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' } ]; ```

#### UserReviewsOptions Same options as [UserRatingsOptions](#userrationsoptions). ## 💻 CLI Tools This library ships with a CLI exposing several tools. Choose the installation method that fits your workflow. ### Installation **Option A: npx** _(no installation required)_ > Runs directly via Node.js ```bash npx node-csfd-api ``` **Option B: Homebrew** _(macOS)_ ```bash brew install bartholomej/tap/csfd ``` **Option C: Install script** _(macOS & Linux)_ > Installs the latest stable release as a standalone binary to `~/.local/bin/csfd`. ```bash 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 ``` **Option D: Windows** _(manual download)_ Download `csfd-windows-x64.zip` from the [latest release](https://github.com/bartholomej/node-csfd-api/releases/latest), extract `csfd.exe`, and add it to your `PATH`. > ⚠️ Windows may show a SmartScreen warning ("Windows protected your PC") because the binary is not code-signed. To proceed: click **More info** → **Run anyway**. Alternatively, right-click the `.exe` → Properties → check **Unblock**. --- ### CLI Examples > 💡 The examples below use `csfd` (Options B, C & D). If you use npx, replace it with `npx node-csfd-api` — e.g. `npx node-csfd-api export ratings 912`. #### 1. Search ```bash 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. Movie Details ```bash 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. Export Ratings (CSV, JSON & Letterboxd) > Backup your personal user ratings. _Use this tool just to keep a local copy of your data._ ```bash csfd export ratings 912 # CSV (default) -> -ratings.csv # npx node-csfd-api export ratings 912 csfd export ratings 912 --json # JSON -> -ratings.json # npx node-csfd-api export ratings 912 --json csfd export ratings 912 --letterboxd # Letterboxd CSV -> -for-letterboxd.csv # npx node-csfd-api export ratings 912 --letterboxd ``` #### 3. Export Reviews (CSV & JSON) ```bash csfd export reviews 912 # CSV (default) -> -reviews.csv # npx node-csfd-api export reviews 912 csfd export reviews 912 --json # JSON -> -reviews.json # npx node-csfd-api export reviews 912 --json ``` #### 4. REST API Server ```bash csfd server # npx node-csfd-api server ``` #### 5. MCP Server for AI Agents ```bash csfd mcp # npx node-csfd-api mcp ``` ## 🤖 MCP Server (Model Context Protocol) This library includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. This allows you to use ČSFD data directly within LLMs like **Claude Desktop**. ### Features - **Search**: Search for movies, TV series, and users. - **Details**: Get comprehensive details about movies, creators, and users. - **Reviews**: Read user reviews and ratings. ### Usage with Claude Desktop Add the following configuration to your `claude_desktop_config.json`: ```json { "mcpServers": { "csfd": { "command": "npx", "args": ["-y", "node-csfd-api", "mcp"] } } }

CSFD API MCP Server

Installation