Skip to main content
The MCP (Model Context Protocol) server allows AI tools like Claude Desktop to query ČSFD data directly using natural language.

​
What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data sources and tools. Think of it as a way for AI models to “know” about ČSFD movies without you having to copy-paste data.
Learn more about MCP at modelcontextprotocol.io

​
Quick Start

​
Running the Server

npx node-csfd-api mcp
You should see: 
--- CSFD MCP Server (v5.1.0) ---
Status: Running via Stdio

To use this server in Claude Desktop, add this to your config:
{
  "node-csfd-api": {
    "command": "npx",
    "args": ["-y", "node-csfd-api", "mcp"]
  }
}
The MCP server communicates via stdio (standard input/output). Don’t run it directly in your terminal - it’s meant to be launched by AI tools like Claude Desktop.

​
Integration with Claude Desktop

1

Locate Claude Config File

The configuration file location depends on your OS:
~/Library/Application Support/Claude/claude_desktop_config.json
2

Edit the Config File

Add the ČSFD MCP server to the mcpServers section:
claude_desktop_config.json
{
  "mcpServers": {
    "csfd": {
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"]
    }
  }
}
If you installed via Homebrew, you can use:
{
  "mcpServers": {
    "csfd": {
      "command": "csfd",
      "args": ["mcp"]
    }
  }
}
3

Restart Claude Desktop

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

Verify Integration

In Claude Desktop, you should see a small tool icon indicating available MCP servers. Try asking:
“Search for Quentin Tarantino movies on ČSFD”

​
Available MCP Tools

The MCP server exposes 6 tools that Claude can use: Search for movies, TV series, or people on ČSFD. Tool name: search Input:
  • query (string) - Search query (movie title, actor name, etc.)
Example Claude prompt:
“Search ČSFD for movies with Tom Hanks”

​
2. Get Movie

Retrieve detailed information about a specific movie or series. Tool name: get_movie Input:
  • id (number) - ČSFD movie ID
What it returns:
  • Title, year, rating, genres
  • Plot descriptions
  • Cast and crew
  • VOD availability
  • Premiere dates
  • Trivia
Example Claude prompt:
“Get details about ČSFD movie ID 535121”

​
3. Get Creator

Retrieve information about actors, directors, and other creators. Tool name: get_creator Input:
  • id (number) - ČSFD creator ID
What it returns:
  • Name, biography
  • Birthday, birthplace
  • Age, photo
  • Complete filmography
Example Claude prompt:
“Show me Quentin Tarantino’s filmography from ČSFD”

​
4. Get User Ratings

Retrieve movie ratings from a specific ČSFD user. Tool name: get_user_ratings 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 in ms
  • excludes (array, optional) - Content types to exclude
  • includesOnly (array, optional) - Content types to include
Example Claude prompts:
“What movies has ČSFD user 912 rated recently?” “Get all film ratings from user 912-bart, excluding TV series”

​
5. Get User Reviews

Retrieve detailed reviews written by a ČSFD user. Tool name: get_user_reviews Input:
  • Same parameters as get_user_ratings
What it returns:
  • Review text
  • User rating (0-5 stars)
  • Review date
  • Movie details
Example Claude prompt:
“Show me the latest reviews from ČSFD user 195357”

​
6. Get Cinemas

Retrieve cinema screenings for a given district. Tool name: get_cinemas Input:
  • district (number | string) - District ID or name
  • period (enum) - Time period: today, tomorrow, weekend, week, month
Example Claude prompt:
“What’s showing in Prague cinemas this weekend?”

​
Available MCP Prompts

The server includes pre-built prompt templates:

​
Actor Top Rated

Finds and ranks the best movies of a specific actor or creator. Prompt name: actor-top-rated Input:
  • actorName (string) - Name of the actor or director
What it does:
  1. Searches for the person
  2. Retrieves their full profile
  3. Analyzes their filmography
  4. Returns top 5 highest-rated movies
Example Claude prompt:
“Use the actor-top-rated prompt for Mads Mikkelsen”

​
Real-World Usage Examples

​
Finding Movie Information

What's the ČSFD rating for the movie "Dragged Across Concrete"?

​
Analyzing User Preferences

Analyze user 912's ratings and tell me their favorite genres

​
Creator Filmography

Show me S. Craig Zahler's highest-rated films on ČSFD

​
Advanced Configuration

​
Using Local Build (Development)

If you’re developing or testing local changes:
1

Build the Project

git clone https://github.com/bartholomej/node-csfd-api.git
cd node-csfd-api
yarn install
yarn build
2

Update Claude Config

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

​
Debugging

Enable debug logging by checking Claude Desktop’s log files: 
tail -f ~/Library/Logs/Claude/mcp*.log

​
Troubleshooting

  1. Check that claude_desktop_config.json is valid JSON (use a validator)
  2. Ensure you fully restarted Claude Desktop (quit completely, not just close window)
  3. Check Claude’s logs for error messages
  4. Verify npx node-csfd-api mcp runs successfully in terminal
If using npx:
{
  "command": "npx",
  "args": ["-y", "node-csfd-api", "mcp"]
}
The -y flag ensures npx doesn’t prompt for confirmation.If using Homebrew csfd command:
{
  "command": "csfd",
  "args": ["mcp"]
}
MCP tools make real-time requests to ČSFD:
  • search is fast (~1s)
  • get_movie is fast (~1s)
  • get_user_ratings with allPages=true can take minutes for large collections
Tip: For user ratings, start with page=1 to get quick results, then use allPages only when needed.
If Claude reports an unexpected MCP server version:
# Clear npx cache
npx clear-npx-cache

# Or force reinstall
npx -y node-csfd-api@latest mcp

​
Security Considerations

The MCP server runs locally on your machine and makes direct requests to ČSFD.cz. Consider:
  • No API key required (it’s your local machine)
  • All requests come from your IP address
  • ČSFD may rate-limit excessive requests
  • User data is fetched in real-time (not cached)
Best practices:
  • Use allPagesDelay when fetching large datasets
  • Don’t share your claude_desktop_config.json (may contain other sensitive servers)
  • Be mindful of ČSFD’s terms of service

​
Next Steps

MCP Documentation

Learn more about the Model Context Protocol

CLI Overview

Explore other CLI tools

API Reference

See the underlying API methods

Build docs developers (and LLMs) love

Get started for freeTalk to us