MCP Integration

The ČSFD API includes a built-in Model Context Protocol (MCP) server, allowing you to use ČSFD data directly within Large Language Models like Claude Desktop.

What is MCP?

Model Context Protocol (MCP) is a standard protocol that allows AI assistants to access external data sources and tools. With MCP, Claude Desktop and other AI assistants can:

Search for movies and creators on ČSFD
Retrieve detailed information about films
Access user ratings and reviews
Get cinema screenings

All in real-time, directly from natural language conversations.

Features

The ČSFD MCP server provides the following capabilities:

Search

Search for movies, TV series, creators, and users

Movie Details

Get comprehensive movie information including ratings, cast, and plot

Creator Info

Access biographies and filmographies

User Data

Retrieve user ratings and reviews

Quick Start with Claude Desktop

The easiest way to use the MCP server is with Claude Desktop.

Locate your Claude Desktop config

Find the configuration file:

macOS
Windows

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

Add ČSFD MCP server configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "csfd": {
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"]
    }
  }
}

If you already have other MCP servers configured, just add the csfd entry to your existing mcpServers object.

Restart Claude Desktop

Close and reopen Claude Desktop for the changes to take effect.

Test it out

Try asking Claude:

“Search for Inception on ČSFD”
“Get details about Quentin Tarantino”
“What are the top rated movies by Christopher Nolan?”

Available MCP Tools

The ČSFD MCP server exposes 6 tools that AI assistants can use:

1. Search

Description: Search for movies, TV series, or people on ČSFD.cz Input:

query (string): Search query (movie title, actor name, etc.)

Returns: Lists of matching movies, TV series, creators, and users with their IDs

This is usually the first tool to use - it returns IDs that other tools need.

2. Get Movie

Description: Retrieve detailed information about a specific movie or series Input:

id (number): ČSFD movie ID (obtained from search)

Returns: Comprehensive movie data including:

Title, year, rating, and poster
Plot descriptions and trivia
Genres and origins
Cast and crew
VOD platforms
Premieres and related movies

3. Get Creator

Description: Get information about a creator (actor, director, etc.) Input:

id (number): ČSFD creator ID

Returns:

Name and biography
Birthday and birthplace
Photo
Complete filmography

4. Get User Ratings

Description: Retrieve movie ratings from a ČSFD user profile Input:

user (string | number): User ID or username
page (number, optional): Page number
allPages (boolean, optional): Fetch all pages
allPagesDelay (number, optional): Delay between requests (ms)
excludes (array, optional): Film types to exclude
includesOnly (array, optional): Film types to include

Returns: Array of rated movies with user ratings (0-5 stars)

5. Get User Reviews

Description: Retrieve detailed reviews written by a ČSFD user Input: Same as Get User Ratings Returns: Array of reviews with full text and ratings

6. Get Cinemas

Description: Get cinema screenings for a specific district Input:

district (string | number): District ID or name
period (enum): Time period (today, tomorrow, weekend, week, month)

Returns: List of cinemas with their screenings and showtimes

Usage Examples

Here are some example prompts you can use with Claude Desktop:

Movie Search
Actor Filmography
User Analysis
Cinema Showtimes

Prompt:

“Find the movie ‘Interstellar’ on ČSFD and tell me its rating”

Claude will:

Use the search tool to find Interstellar
Use the get_movie tool with the ID
Return the rating and other details

Prompt:

“What’s playing in Prague cinemas this weekend?”

Claude will:

Use the get_cinemas tool for Prague district
Filter for weekend period
Return cinema listings with showtimes

Built-in Prompts

The MCP server includes pre-built prompts for common tasks:

Actor Top Rated

Description: Finds and ranks the best movies of a specific actor or creator Usage:

Find top rated movies by Mads Mikkelsen

This prompt automatically:

Searches for the person
Retrieves their profile
Identifies top 5 highest-rated movies
Returns a formatted list

Running the MCP Server Manually

You can also run the MCP server directly from the command line:

NPX
Global Install
Local Development

npx node-csfd-api mcp

# Install globally first
npm install -g node-csfd-api

# Run the server
csfd mcp

# Clone the repo
git clone https://github.com/bartholomej/node-csfd-api.git
cd node-csfd-api

# Install dependencies
yarn install

# Build
yarn build

# Run MCP server
yarn mcp

Configuration for Other AI Assistants

While Claude Desktop is the primary target, the MCP server can work with any MCP-compatible AI assistant.

Generic MCP Client Configuration

{
  "name": "csfd",
  "command": "npx",
  "args": ["-y", "node-csfd-api", "mcp"],
  "transport": "stdio"
}

Troubleshooting

Claude doesn't recognize ČSFD tools

Solution:

Verify your claude_desktop_config.json is correctly formatted
Make sure you restarted Claude Desktop after making changes
Check that npx is available in your PATH:
```
npx --version
```

Tools return errors

Solution:

Check your internet connection
Verify the ČSFD website is accessible
Try running the MCP server manually to see error messages:
```
npx node-csfd-api mcp
```

Slow responses

Solution:

The MCP server scrapes data from ČSFD.cz in real-time, so some delay is normal
For faster responses, consider running your own REST API server with caching

Rate limiting issues

Solution:

When fetching all pages of user ratings/reviews, use the allPagesDelay parameter
Avoid making too many requests in a short time
Consider implementing your own caching layer

Advanced Configuration

Using a Local Build

For development or if you want to modify the MCP server:

claude_desktop_config.json

{
  "mcpServers": {
    "csfd-local": {
      "command": "node",
      "args": ["/path/to/node-csfd-api/dist/bin/mcp-server.mjs"]
    }
  }
}

Environment Variables

You can pass environment variables to the MCP server:

{
  "mcpServers": {
    "csfd": {
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Privacy & Security

The MCP server does not collect, store, or transmit any user data. All requests go directly from your machine to ČSFD.cz.

No data is logged or stored
No intermediary servers are involved
All scraping happens in real-time from your local machine
Respects ČSFD’s terms of service

Next Steps

TypeScript Types

Explore the type definitions for MCP responses

REST API

Run your own ČSFD API server

Get Started

Core Features

CLI Tools

Advanced

Examples

What is MCP?

Features

Search

Movie Details

Creator Info

User Data

Quick Start with Claude Desktop

Available MCP Tools

1. Search

2. Get Movie

3. Get Creator

4. Get User Ratings

5. Get User Reviews

6. Get Cinemas

Usage Examples

Built-in Prompts

Actor Top Rated

Running the MCP Server Manually

Configuration for Other AI Assistants

Generic MCP Client Configuration

Troubleshooting

Advanced Configuration

Using a Local Build

Environment Variables

Privacy & Security

Next Steps

TypeScript Types

REST API

Build docs developers (and LLMs) love

Get Started

Core Features

CLI Tools

Advanced

Examples

​What is MCP?

​Features

Search

Movie Details

Creator Info

User Data

​Quick Start with Claude Desktop

​Available MCP Tools

​1. Search

​2. Get Movie

​3. Get Creator

​4. Get User Ratings

​5. Get User Reviews

​6. Get Cinemas

​Usage Examples

​Built-in Prompts

​Actor Top Rated

​Running the MCP Server Manually

​Configuration for Other AI Assistants

​Generic MCP Client Configuration

​Troubleshooting

​Advanced Configuration

​Using a Local Build

​Environment Variables

​Privacy & Security

​Next Steps

TypeScript Types

REST API

Build docs developers (and LLMs) love

What is MCP?

Features

Quick Start with Claude Desktop

Available MCP Tools

1. Search

2. Get Movie

3. Get Creator

4. Get User Ratings

5. Get User Reviews

6. Get Cinemas

Usage Examples

Built-in Prompts

Actor Top Rated

Running the MCP Server Manually

Configuration for Other AI Assistants

Generic MCP Client Configuration

Troubleshooting

Advanced Configuration

Using a Local Build

Environment Variables

Privacy & Security

Next Steps