Movies, TV series, creators and user ratings from ČSFD.cz, the Czech-Slovak film database
The io.github.bartholomej/node-csfd-api MCP server provides access to movies, TV series, creators, and user ratings from ČSFD.cz, the Czech-Slovak film database. It is identified by the slug io-github-bartholomej-node-csfd-api and is described as an API focused on ČSFD.cz content.
🛠️ Key Features
Access to movies
Access to TV series
Access to creators
Access to user ratings from ČSFD.cz
🚀 Use Cases
Retrieve ČSFD.cz movie and TV series data
Look up creators associated with titles
Use user ratings from the ČSFD.cz film database
⚡ Developer Benefits
Source of ČSFD.cz-derived content for developers working with Czech-Slovak film data
⚠️ Limitations
Available details are limited to the server’s scope (movies, TV series, creators, user ratings); no other capabilities, tooling count, or configuration information is provided.
import { csfd } from'node-csfd-api';
const results = await csfd.search('bart');
// Access different result typesconsole.log(results.movies); // Array of moviesconsole.log(results.tvSeries); // Array of TV seriesconsole.log(results.users); // Array of users
Get detailed information about a creator including their biography and filmography.
Method:csfd.creator(id: number | string, options?: CSFDOptions): Promise<CSFDCreator>
typescript
import { csfd } from'node-csfd-api';
const creator = await csfd.creator(2120); // Quentin Tarantinoconsole.log(creator.name); // Nameconsole.log(creator.bio); // Biographyconsole.log(creator.films); // Filmographyconsole.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'
}
]
}
Charts
ČSFD's charts of movies and series: the best and worst rated, the most favourited and the most controversial.
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.
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>
typescript
import { csfd } from'node-csfd-api';
const user = await csfd.user(912); // also '912-bart' or a profile URLconsole.log(user.user); // Nicknameconsole.log(user.userRealName); // Real nameconsole.log(user.ratingsCount); // All ratings, not just the first page
Č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:
typescript
import { getAnubisCookie, resetAnubisCookie, setAnubisCookie } from'node-csfd-api';
const cookie = getAnubisCookie(); // Save it, e.g. to a file or a databasesetAnubisCookie(cookie); // Restore it on the next startresetAnubisCookie(); // 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
bash
npx node-csfd-api <command>
Option B: Homebrew(macOS & Linux)
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.
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 with npx node-csfd-api — e.g. npx node-csfd-api export ratings 912.
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
bash
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.
The REST server also serves MCP at /mcp, so one running instance, e.g. the Docker image, can be shared by several clients. It is protected by the same API_KEY as the REST API, sent as a bearer token.
bash
docker run -p 3000:3000 -e API_KEY=my-secret bartholomej/node-csfd-api
search: Search movies, TV series, creators and users (returns IDs for the other tools)
get_movie: Movie or TV series details by ID
get_creator: Creator details and filmography by ID
get_user: User profile (nickname, real name, member since, totals)
get_user_ratings: User ratings (by page)
get_user_reviews: User reviews (by page)
get_cinemas: Cinema showtimes
get_chart: Movie or series chart (best, worst, favorite, controversial)
Every tool returns structured data with a declared output schema, so clients know which fields to expect. There is also an actor-top-rated prompt that finds and ranks the best movies of an actor or creator.
🐳 Docker Support
Run the CSFD API as a standalone REST service using Docker.
Using Pre-built Image
bash
# Pull the latest image
docker pull bartholomej/node-csfd-api
# Run the container
docker run -p 3000:3000 bartholomej/node-csfd-api
Building Your Own Image
bash
# Build the image
docker build -t node-csfd-api .
# Run the container
docker run -p 3000:3000 node-csfd-api
REST API
Start the server with Docker (above), csfd server or npx node-csfd-api server, then access it at http://localhost:3000. The same server also serves MCP over HTTP at /mcp.
Endpoint
Description
Example
/movie/:id
Movie or TV series details
/movie/535121
/search/:query
Search
/search/tarantino
/creator/:id
Creator details
/creator/2120
/user/:id
User profile
/user/912-bart
/user-ratings/:id
User ratings
/user-ratings/912-bart?page=2
/user-reviews/:id
User reviews
/user-reviews/195357?allPages=true
/cinemas
Today's showtimes in Praha
/cinemas
/chart/:type/:category
Movie or series chart
/chart/movies/best?limit=100
All endpoints accept ?language=cs|en|sk. User ratings and reviews also accept page, allPages, allPagesDelay, includesOnly and excludes (comma-separated, e.g. ?excludes=episode,season). Charts take movies or series and best, worst, favorite or controversial, plus an optional limit (places 1–99 without it).
Configuration (environment variables):
Variable
Description
PORT
Port to listen on (default 3000)
API_KEY
One or more comma-separated keys. When set, every request must send one of them
API_KEY_NAME
Alternative header carrying the key (default x-api-key)
LANGUAGE
Default language: cs, en or sk
VERBOSE
Set to true to log successful requests as well
Send the key as a bearer token, or in the API_KEY_NAME header:
Your support helps maintain and improve this library! 🙏
🔒 Privacy & Security
This library does not collect, store, or transmit any user data.
All requests are made directly from your application to ČSFD.cz. No intermediary servers are involved, and no data is logged or stored by this library.
I physically can't. I have nowhere to store it. I don't even have a server database to store it. So even if Justin Bieber asked nicely to see your data, I wouldn't have anything to show him.
Important Notes
This is a scraping library - use it responsibly and respect ❤️ ČSFD's terms of service
Implement appropriate rate limiting in production
Consider caching responses to minimize server load
Be aware of CORS restrictions when using in browsers