ČSFD

✨ 功能

• 🎯 类型安全 - 全面支持 TypeScript，并提供类型定义
• 🧪 测试完善 - 代码覆盖率约为 100%
• 🚀 通用 - 可在 Node.js、浏览器和无服务器环境中运行
• 🐳 支持 Docker - 提供预构建的 Docker 镜像
• 🍺 支持 Homebrew - 通过 Homebrew tap 轻松全局安装命令行工具
• 🤖 MCP 服务 - 可在 Claude Desktop 等大模型中直接使用 CSFD 数据
• 🔄 现代 API - 基于 Promise，并支持 async/await
• 📦 依赖少 - 轻量且高效

支持的平台

• Node.js（ESM 和 CommonJS）
• 浏览器（需考虑 CORS）
• Docker 容器
• macOS/Linux 命令行工具（通过 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
• 命令行工具
• MCP 服务
• Docker 支持
• REST API
• 开发

📚 API 参考

电影

根据 ČSFD ID 获取电影或电视剧的详细信息。

方法： csfd.movie(id: number | string, options?: CSFDOptions): Promise<CSFDMovie>

ID 可以是数字、slug（'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 会对每一页发送一次请求。请在请求之间设置延迟（allPagesDelay），避免给 Č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
  }
];

📝 注意：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 地址绑定，有效期约为一周，因此你可以在多次运行之间保留它：

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 已保护你的电脑”），因为此二进制文件未经代码签名。若要继续：点击 更多信息 → 仍要运行。或者，右键点击 .exe →“属性”→ 勾选 解除锁定。

CLI 示例

💡 以下示例使用 csfd（选项 B、C 和 D）。如果使用 npx，请将其替换为 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 Agent 的 MCP 服务

csfd mcp
# npx node-csfd-api mcp

🤖 MCP 服务（模型上下文协议）

此库内置了一个 模型上下文协议（MCP）服务。借助它，你可以直接在 Claude Desktop 等大模型中使用 Č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 - 将 ČSFD 集成到 Dafilms（源代码）
• Kviff.tv Extension - Kviff.tv 的 ČSFD 评分（源代码）

Web 应用

• bartweb.cz - 使用 Firebase Functions 跟踪“最近观看”电影的个人网站

移动应用

• KinoKlub - 面向 AeroFilms 影院连锁的 React Native 应用（Android 和 iOS）

🔮 路线图

已完成功能 ✅

• 电影和电视剧
  • 基本信息（片名、年份、评分、海报、时长）
  • 详细元数据（类型、来源、点播平台）
  • 演职人员（导演、演员、编剧、作曲、制片人等）
  • 相关内容（相似电影、趣闻）
  • 其他片名、首映、标签
• 搜索
  • 电影、电视剧、创作者和用户
• 创作者
  • 个人简介和影视作品
• 用户数据
  • 支持分页和筛选的评分
  • 支持分页和筛选的评论

计划中的功能 🚧

• 搜索：创作者搜索功能
• 电影：电影详情页中的评论
• 电影：原声带（OST）信息
• 服务端：用于提升性能的缓存层
• 服务端：速率限制辅助工具

🛠️ 开发

想在本地运行项目、从源码启动 REST 或 MCP 服务，或者运行测试？所有内容都在 CONTRIBUTING.md 中。

🤝 贡献

欢迎贡献！提交拉取请求前，请阅读 CONTRIBUTING.md。

发现了错误或有想法？提交议题。

⭐️ 支持

如果你觉得这个项目有用，也愿意支持，不妨捐赠，请我喝点 🍺 或 🍵 ;)

• 在 GitHub 上点个 ⭐️
• 分享给可能会从中受益的人
• 赞助项目，支持持续开发

你的支持有助于维护和改进这个库！🙏

🔒 隐私与安全

本库不会收集、存储或传输任何用户数据。

所有请求都由你的应用直接发送至 ČSFD.cz。不涉及任何中间服务，本库也不会记录或存储任何数据。

我确实做不到。我没有地方存储这些数据，甚至没有服务器数据库可以存储。所以，即便 Justin Bieber 客气地请求查看你的数据，我也无可奉告。

重要说明

• 这是一个抓取库——请负责任地使用，并遵守 ❤️ ČSFD 的服务条款
• 在生产环境中实施适当的速率限制
• 考虑缓存响应以尽量减轻服务器负载
• 在浏览器中使用时，请留意 CORS 限制

📝 许可证

MIT © 2020 - 2026 Lukas Bartak

完整详情请参阅 LICENSE。