
ČSFD
io.github.bartholomejv5.13.1更新於 Oct 10, 2026
Movies, TV series, creators and user ratings from ČSFD.cz, the Czech-Slovak film database
概覽
讓助理搜尋捷克-斯洛伐克電影資料庫 ČSFD,並取得影片、影集、創作者、評分與評論資訊。
- 功能
- 把非官方的 node-csfd-api 擷取程式庫包裝成 MCP 伺服器,提供搜尋電影、影集、創作者與使用者的工具,以及依 ID 取得詳細資料的工具。包含 get_movie、get_creator、get_user_ratings、get_user_reviews 與 get_cinemas,搜尋工具會回傳其他工具所需的 ID。另有 actor-top-rated 提示詞,可依評分排序某位創作者的作品。回傳結果為具備輸出結構定義的結構化資料。
- 適用情境
- 適合助理需要捷克或斯洛伐克影視資料的情境:片名、年份、類型、評分、創作者、作品清單、使用者評分與評論,以及布拉格戲院場次。它是唯讀查詢服務,適合圍繞 ČSFD 內容的推薦、研究與編目類問題。
- 執行需求
- 以本機 Node.js 程序執行,通常用 npx node-csfd-api mcp 啟動,因此需要 Node.js 以及連線至 csfd.cz 的網路。此 MCP 伺服器未宣告帳號、API 金鑰或環境變數。清單標示為僅限桌面端。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 ČSFD,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
[npm version] [License] [Build & Publish] [Coverage] [npm downloads]
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
🚀 Quick Start
📖 Table of Contents
- Movie Details
- Search
- Creators
- 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.
🔎 Click here to see full result example
Search
Search for movies, TV series, creators and users across the ČSFD database.
Method: csfd.search(query: string, options?: CSFDOptions): Promise<CSFDSearch>
🔎 Click here to see full result example
Creators
Get detailed information about a creator including their biography and filmography.
Method: csfd.creator(id: number | string, options?: CSFDOptions): Promise<CSFDCreator>
🔎 Click here to see full result example
User Ratings
Retrieve user ratings from their ČSFD profile.
Method: csfd.userRatings(user: number | string, config?: CSFDUserRatingConfig, options?: CSFDOptions): Promise<CSFDUserRatings[]>
Basic Usage
Advanced Options
⚠️ Be considerate:
allPagessends one request per page. Keep a delay between them (allPagesDelay) so you don't put unnecessary load on ČSFD.
🔎 Click here to see full result example
CSFDUserRatingConfig
📝 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
Advanced Options
🔎 Click here to see full result example
CSFDUserReviewsConfig
Same options as CSFDUserRatingConfig.
Language & Request Options
Every method accepts CSFDOptions as its last argument:
Error Handling
When a page can't be fetched, methods reject with a CsfdError. Its reason tells you why:
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:
💻 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
Option B: Homebrew (macOS & Linux)
Option C: Install script (macOS & Linux)
Installs the latest stable release as a standalone binary to
~/.local/bin/csfd.
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
2. Movie Details
3. Export Ratings (CSV, JSON & Letterboxd)
Backup your personal user ratings. Use this tool just to keep a local copy of your data.
3. Export Reviews (CSV & JSON)
4. REST API Server
5. MCP Server for AI Agents
🤖 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.
Features
- Search: Search for movies, TV series, creators and users.
- Details: Get comprehensive details about movies and creators.
- Users: Read user ratings and reviews.
Usage with Claude Desktop
Add the following configuration to your claude_desktop_config.json:
Other Clients
Claude Code
Cursor: add the same mcpServers configuration as for Claude Desktop to ~/.cursor/mcp.json (or .cursor/mcp.json in your project).
VS Code: add this to .vscode/mcp.json in your project:
Supported Tools
search: Search movies, TV series, creators and users (returns IDs for the other tools)get_movie: Movie or TV series details by IDget_creator: Creator details and filmography by IDget_user_ratings: User ratings (by page)get_user_reviews: User reviews (by page)get_cinemas: Cinema showtimes
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
Building Your Own Image
REST API
Start the server with Docker (above), csfd server or npx node-csfd-api server, then access it at http://localhost:3000:
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).
Configuration (environment variables):
Errors are returned as JSON ({ "error": "MOVIE_FETCH_FAILED", "message": "…" }) with a matching status:
Docker Hub: bartholomej/node-csfd-api
🌟 Real-World Usage
This library powers several production applications:
Browser Extensions
- Netflix ČSFD Extension - Shows ČSFD ratings on Netflix (source)
- Dafilms Extension - ČSFD integration for Dafilms (source)
- Kviff.tv Extension - ČSFD ratings for Kviff.tv (source)
Web Applications
- bartweb.cz - Personal website using Firebase Functions for "Last Seen" movie tracking
Mobile Applications
- KinoKlub - React Native app for AeroFilms cinema chain (Android & iOS)
🔮 Roadmap
Completed Features ✅
- Movies & TV Series
- Basic info (title, year, rating, poster, duration)
- Detailed metadata (genres, origins, VOD platforms)
- Cast & crew (directors, actors, writers, composers, producers, etc.)
- Related content (similar movies, trivia)
- Alternative titles, premieres, tags
- Search
- Movies, TV series, Creators and users
- Creators
- Biography and filmography
- User Data
- Ratings with pagination and filtering
- Reviews with pagination and filtering
Planned Features 🚧
- Search: Creator search functionality
- Movie: reviews from movie detail page
- Movie: Original soundtracks (OST) information
- Server: Caching layer for improved performance
- Server: Rate limiting helpers
🛠️ Development
Want to run the project locally, start the REST or MCP server from source, or run the tests? Everything is in CONTRIBUTING.md.
🤝 Contributing
Contributions are welcome! Read CONTRIBUTING.md before opening a pull request.
Found a bug or have an idea? Open an issue.
⭐️ Support
If you find this project useful and you are brave enough consider making a donation for some 🍺 or 🍵 ;)
- Giving it a ⭐️ on GitHub
- Sharing it with others who might benefit
- Sponsoring the project to support ongoing development
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
📝 License
MIT © 2020 - 2026 Lukas Bartak
See LICENSE for full details.
Built with ❤️ by Lukas Bartak
Powered by nature 🗻, wind 💨, tea 🍵 and beer 🍺
來源:README.md,提交 1a726ba
工具
0版本歷史
1- v5.13.1最新Oct 10, 2026

