チェコ・スロバキアの映画データベースから、映画、テレビシリーズ、クリエイター、ユーザー評価にAIクライアントがアクセスできるようにします。
別名 bartholomej/node-csfd-api, node-csfd-api
- スター
- 66
- ツール
- 8
- ダウンロード数(30日間)
- —
- 最新バージョン
- 5.16.0
- 最終コミット
- 2026年11月12日
- ライセンス
- MIT
ČSFD MCPとは
チェコ・スロバキアの映画データベースから、映画、テレビシリーズ、クリエイター、ユーザー評価にAIクライアントがアクセスできるようにします。 8個のツールを提供しており、search, get_movie, get_creatorなどがあります。
プロジェクトのREADMEから生成された概要
ČSFD MCP server について
このMCP serverは、チェコ・スロバキアの映画データベースから、映画の詳細、テレビシリーズの情報、クリエイターの経歴へのアクセスを可能にします。Claude DesktopなどのAIクライアントがČSFDデータベースと連携し、フィルモグラフィ、ユーザー評価、レビューを含む包括的なデータを取得できます。
ユーザーは、映画、シリーズ、特定のクリエイターの広範な検索を行ったり、特定のIDやスラッグを使用して詳細な情報を調べたりできます。また、最高、最低、最もお気に入り、最も論争を呼んでいるコンテンツといった、専門的なチャートへのアクセスも提供します。Node.js環境での使用を想定して設計されており、Dockerコンテナ経由でデプロイすることで、ローカルまたはリモートのワークフローに簡単に統合できます。
できること
- 1映画コンテンツの検索検索クエリを使用して、データベース内の映画、テレビシリーズ、または特定のユーザーを見つけます。
- 2クリエイターの経歴取得監督や俳優の経歴や全フィルモグラフィを含む詳細情報を取得します。
- 3映画の人気チャート分析コミュニティのランキングに基づき、評価の高い映画やシリーズ、または低いものを特定します。
- 4特定の映画メタデータの取得ジャンル、製作国、キャストなど、特定の映画に関する詳細なメタデータを取得します。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
ČSFD MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude CodeにČSFD MCPをインストール
$ claude mcp add node-csfd-api -- npx -y node-csfd-api mcpCursorにČSFD MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"node-csfd-api": {
"command": "npx",
"args": [
"-y",
"node-csfd-api",
"mcp"
]
}
}
}VS CodeにČSFD MCPをインストール
.vscode/mcp.json
{
"servers": {
"node-csfd-api": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"node-csfd-api",
"mcp"
]
}
}
}VS Code CLIにČSFD MCPをインストール
$ code --add-mcp '{"name":"node-csfd-api","type":"stdio","command":"npx","args":["-y","node-csfd-api","mcp"]}'Claude DesktopにČSFD MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"node-csfd-api": {
"command": "npx",
"args": [
"-y",
"node-csfd-api",
"mcp"
]
}
}
}CodexにČSFD MCPをインストール
$ codex mcp add node-csfd-api -- npx -y node-csfd-api mcpCodex config.tomlにČSFD MCPをインストール
~/.codex/config.toml
[mcp_servers.node-csfd-api] command = "npx" args = ["-y", "node-csfd-api", "mcp"]
Gemini CLIにČSFD MCPをインストール
$ gemini mcp add -s user node-csfd-api npx -- -y node-csfd-api mcpGemini settings.jsonにČSFD MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"node-csfd-api": {
"command": "npx",
"args": [
"-y",
"node-csfd-api",
"mcp"
]
}
}
}HostedMCP が 2026年11月16日 に起動を確認
node-csfd-api 5.16.0 をネットワークもキーもない隔離コンテナでこのコマンドで起動しました。応答があり、8個のツールが一覧表示されました。
ČSFD MCPツール 8
tools/list でサーバーから取得search読み取り専用Searches for a movie, TV series, or person on CSFD.cz. Returns a list of results with IDs. Use this tool FIRST to find the ID needed for other tools.
get_movie読み取り専用Retrieves detailed information about a specific movie or series, including rating, plot, genres, and actors. Requires a numeric CSFD ID.
get_creator読み取り専用Retrieves information about a specific creator (actor, director, etc.), including their biography and filmography. Requires a numeric CSFD ID.
get_user読み取り専用Retrieves a CSFD user's public profile: nickname, real name, location, member since, and the total number of ratings, reviews and fans. Use get_user_ratings or get_user_reviews for the ratings and reviews themselves.
get_user_ratings読み取り専用Retrieves movie ratings from a specific CSFD user. Returns a list of movies with their user rating (0-5 stars). Supports pagination and filtering by film type.
get_user_reviews読み取り専用Retrieves movie reviews written by a specific CSFD user. Returns a list of movies with their review text and rating.
get_cinemas読み取り専用Retrieves cinema screenings for a given district in Czech Republic. Returns a list of cinemas with their current screenings, showtimes, and movie names and ids.
get_chart読み取り専用Retrieves one of CSFD's charts of movies or TV series: the best or worst rated, the most favourite or the most controversial. Returns the places in order with ID, title, year, rating, genres, countries, directors and actors. Without a limit it returns the first page, places 1–99, in one request to CSFD; each further hundred costs another request.
| search | Searches for a movie, TV series, or person on CSFD.cz. Returns a list of results with IDs. Use this tool FIRST to find the ID needed for other tools. | 読み取り専用 |
| get_movie | Retrieves detailed information about a specific movie or series, including rating, plot, genres, and actors. Requires a numeric CSFD ID. | 読み取り専用 |
| get_creator | Retrieves information about a specific creator (actor, director, etc.), including their biography and filmography. Requires a numeric CSFD ID. | 読み取り専用 |
| get_user | Retrieves a CSFD user's public profile: nickname, real name, location, member since, and the total number of ratings, reviews and fans. Use get_user_ratings or get_user_reviews for the ratings and reviews themselves. | 読み取り専用 |
| get_user_ratings | Retrieves movie ratings from a specific CSFD user. Returns a list of movies with their user rating (0-5 stars). Supports pagination and filtering by film type. | 読み取り専用 |
| get_user_reviews | Retrieves movie reviews written by a specific CSFD user. Returns a list of movies with their review text and rating. | 読み取り専用 |
| get_cinemas | Retrieves cinema screenings for a given district in Czech Republic. Returns a list of cinemas with their current screenings, showtimes, and movie names and ids. | 読み取り専用 |
| get_chart | Retrieves one of CSFD's charts of movies or TV series: the best or worst rated, the most favourite or the most controversial. Returns the places in order with ID, title, year, rating, genres, countries, directors and actors. Without a limit it returns the first page, places 1–99, in one request to CSFD; each further hundred costs another request. | 読み取り専用 |
自動チェック
実行日 2026年11月16日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能bartholomej/node-csfd-api is public and reachablegithub.com/bartholomej/node-csfd-api ↗合格
- パッケージがこのリポジトリをソースとして指定node-csfd-api names bartholomej/node-csfd-api as sourcenpmjs.com/package/node-csfd-api ↗合格
- ビルドの来歴 (Sigstore 証明)Sigstore attestation for node-csfd-apinpmjs.com/package/node-csfd-api/v/5.16.0#provenance ↗合格
- オープンソースライセンス (OSI)MITspdx.org/licenses/MIT.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-12github.com/bartholomej/node-csfd-api ↗合格
- OpenSSF ScorecardOpenSSF Scorecard 4.8 / 10; weakest: Code-Review 0, Token-Permissions 0, CII-Best-Practices 0scorecard.dev/viewer/?uri=github.com/bartholomej/node-csfd-a ↗一部 7/15
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from node-csfd-api合格
- パッケージおよびその依存関係に重大な勧告なし12 resolved dependencies checked; no critical advisoryosv.dev ↗合格
- モデルへの隠れた指示がない8 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされているNo tool named like delete, drop or exec合格
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るCSFD API 🎬 + CSFD Export 💾 + CSFD MCP 🤖
Modern TypeScript NPM library for scraping CSFD.CZ. Scraper, API Rest Server, Exporter and MCP Server in one package. (unofficial)
Features • Installation • Quick Start • API Reference • CLI • MCP Server • Docker
✨ Features
- 🎯 Type-safe - Full TypeScript support with type definitions
- 🧪 Well-tested - ~100% code coverage
- 🚀 Universal - Works in Node.js, browsers, and serverless environments
- 🐳 Docker ready - Pre-built Docker images available
- 🍺 Homebrew support - Easy globally installed CLI via Homebrew tap
- 🤖 MCP Server - Use CSFD data directly within LLMs like Claude Desktop
- 🔄 Modern API - Promise-based with async/await support
- 📦 Few dependencies - Lightweight and efficient
Supported Platforms
- Node.js (ESM & CommonJS)
- Browsers (with CORS considerations)
- Docker containers
- macOS/Linux CLI (via Homebrew)
- MCP Server (Claude Desktop, etc.)
- Serverless (Firebase Functions, AWS Lambda, CloudFlare Workers, etc.)
- Chrome Extensions
- React Native (Yes, with Expo too!)
📦 Installation
npm install node-csfd-api
# yarn add node-csfd-api
# pnpm add node-csfd-api
🚀 Quick Start
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);
📖 Table of Contents
- Movie Details
- Search
- Creators
- Charts
- User
- User Ratings
- User Reviews
- Language & Request Options
- Error Handling
- Browser Verification Cookie
- CLI Tools
- MCP Server
- Docker Support
- REST API
- Development
📚 API Reference
Movie
Retrieve comprehensive information about a movie or TV series by its ČSFD ID.
Method: csfd.movie(id: number | string, options?: CSFDOptions): Promise<CSFDMovie>
The ID can be a number, a slug ('535121-na-spatne-strane') or a full ČSFD URL. The same works for creators and users.
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'
}
]
}
Search
Search for movies, TV series, creators and users across the ČSFD database.
Method: 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/'
}
]
Creators
Get detailed information about a creator including their biography and filmography.
Method: 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'
}
]
}
Charts
ČSFD's charts of movies and series: the best and worst rated, the most favourited and the most controversial.
Method: csfd.chart(type: CSFDChartType, category: CSFDChartCategory, config?: CSFDChartConfig, options?: CSFDOptions): Promise<CSFDChartItem[]>
import { csfd } from 'node-csfd-api';
const best = await csfd.chart('movies', 'best'); // places 1–99
const worstSeries = await csfd.chart('series', 'worst', { limit: 10 });
const top300 = await csfd.chart('movies', 'best', { limit: 300 });
console.log(best[0].title); // Vykoupení z věznice Shawshank
console.log(best[0].rating); // 95.4
type:'movies'or'series'category:'best','worst','favorite'or'controversial'config.limit: how many places from the top. By default it's ČSFD's first page, places 1–99, in one request. Each further hundred takes another request, and the whole chart of 1000 places takes ten.
The favourite chart ranks by fans: its items have fans and no rating or ratingCount.
[
{
position: 1,
id: 2294,
title: 'Vykoupení z věznice Shawshank',
year: 1994,
url: 'https://www.csfd.cz/film/2294/prehled/',
type: 'film',
colorRating: 'good',
poster:
'https://image.pmgstatic.com/cache/resized/w1080/files/images/film/posters/162/505/162505167_735db9.jpg',
origins: ['USA'],
genres: ['Drama', 'Krimi'],
creators: {
directors: [
{
id: 2869,
name: 'Frank Darabont',
url: 'https://www.csfd.cz/tvurce/2869-frank-darabont/prehled/'
}
],
actors: [
{
id: 103,
name: 'Tim Robbins',
url: 'https://www.csfd.cz/tvurce/103-tim-robbins/prehled/'
},
{
id: 92,
name: 'Morgan Freeman',
url: 'https://www.csfd.cz/tvurce/92-morgan-freeman/prehled/'
}
]
},
rating: 95.4,
ratingCount: 116917,
fans: null
}
// …
];
User
Get a user's public ČSFD profile: nickname, real name, avatar, member since and totals.
Method: csfd.user(user: number | string, options?: CSFDOptions): Promise<CSFDUser>
import { csfd } from 'node-csfd-api';
const user = await csfd.user(912); // also '912-bart' or a profile URL
console.log(user.user); // Nickname
console.log(user.userRealName); // Real name
console.log(user.ratingsCount); // All ratings, not just the first page
{
id: 912,
user: 'BART!',
userRealName: 'Lukáš Barták',
avatar: 'https://image.pmgstatic.com/cache/resized/w100h132/files/images/user/avatars/000/281/281554_1c0fef.jpg',
url: 'https://www.csfd.cz/uzivatel/912-bart/',
location: 'Byen København, Hovedstaden, Dánsko',
about: 'Danskjävlar',
memberSince: '2003-03-15',
ratingsCount: 3132,
reviewsCount: 12,
fans: 54,
points: 31
}
Fields a profile doesn't show (no real name, no reviews yet) are null.
User Ratings
Retrieve user ratings from their ČSFD profile.
Method: csfd.userRatings(user: number | string, config?: CSFDUserRatingConfig, options?: CSFDOptions): Promise<CSFDUserRatings[]>
Basic Usage
import { csfd } from 'node-csfd-api';
// Latest ratings (first page, ~50 items)
const ratings = await csfd.userRatings('912-bart');
Advanced Options
// 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']
});
⚠️ Be considerate:
allPagessends one request per page. Keep a delay between them (allPagesDelay) so you don't put unnecessary load on ČSFD.
[
{
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
}
];
CSFDUserRatingConfig
| Option | Type | Default | Description |
|---|---|---|---|
includesOnly |
CSFDFilmTypes[] |
null |
Include only specific content types (e.g., ['film', 'series']) |
excludes |
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:
includesOnlyandexcludesare mutually exclusive. If both are provided,includesOnlytakes precedence.🔗 See CSFDFilmTypes definition
User Reviews
Retrieve detailed user reviews from their ČSFD profile.
Method: csfd.userReviews(user: number | string, config?: CSFDUserReviewsConfig, options?: CSFDOptions): Promise<CSFDUserReviews[]>
Basic Usage
import { csfd } from 'node-csfd-api';
// Get latest reviews
const reviews = await csfd.userReviews(195357);
Advanced Options
// 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
Same options as CSFDUserRatingConfig.
Language & Request Options
Every method accepts CSFDOptions as its last argument:
| Option | Type | Description |
|---|---|---|
language |
'cs' | 'en' | 'sk' |
Language of titles, genres etc. (default cs) |
request |
RequestInit |
Extra fetch options, e.g. custom headers or an abort signal |
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' });
Error Handling
When a page can't be fetched, methods reject with a CsfdError. Its reason tells you why:
reason |
Meaning |
|---|---|
not-found |
The movie, creator or user doesn't exist (HTTP 404) |
blocked |
ČSFD declined the request, e.g. too many requests |
http |
ČSFD answered with another error status |
network |
The request didn't complete (offline, DNS, timeout, …) |
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})`);
}
}
Browser Verification Cookie
ČSFD sometimes asks visitors to complete a short browser verification. The library completes it automatically and reuses the resulting cookie for the following requests. The cookie is tied to your IP address and stays valid for about a week, so you can keep it between runs:
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 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
npx node-csfd-api <command>
Option B: Homebrew (macOS & Linux)
brew install bartholomej/tap/csfd
Option C: Install script (macOS & Linux)
Installs the latest stable release as a standalone binary to
~/.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
Option D: Windows (manual download)
Download csfd-windows-x64.zip from the latest release, 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 withnpx node-csfd-api— e.g.npx node-csfd-api export ratings 912.
1. Search
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
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. User Profile
csfd user 912 # by ID, slug (912-bart) or profile URL
# npx node-csfd-api user 912
csfd user 912 --json # raw JSON output
# npx node-csfd-api user 912 --json
4. Export Ratings (CSV, JSON & Letterboxd)
Backup your personal user ratings. Use this tool just to keep a local copy of your data.
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
5. Export Reviews (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
6. REST API Server
csfd server
# npx node-csfd-api server
7. MCP Server for AI Agents
csfd mcp
# npx node-csfd-api mcp
🤖 MCP Server (Model Context Protocol)
This library includes a built-in Model Context Protocol (MCP) server. This allows you to use ČSFD data directly within LLMs like Claude Desktop.
ČSFD MCPのよくある質問
ČSFD MCPをClaude Codeに追加するには
ターミナルでclaude mcp add node-csfd-api -- npx -y node-csfd-api mcpを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
ČSFD MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
ČSFD MCPが提供するツールは
8個のツールを提供しており、search, get_movie, get_creator, get_user, get_user_ratingsなどがあります。
このサーバーを使って何を検索できますか?
ČSFDデータベース内の映画、テレビシリーズ、クリエイター、ユーザーを検索できます。
特定の映画クリエイターに関する情報を取得できますか?
はい、経歴やフィルモグラフィを含むクリエイターの詳細情報を取得できます。
映画チャートはサポートしていますか?
はい、ČSFDのチャートにアクセスして、最高、最低、最もお気に入り、最も論争を呼んでいる映画やシリーズを確認できます。