Claude Desktop Integration

Claude Desktop can access ČSFD data directly through the MCP (Model Context Protocol) server. This guide shows you how to configure and use the integration.

Prerequisites

Claude Desktop installed
Node.js 18+ installed
Basic familiarity with JSON configuration files

Configuration

Locate the config file

Find your Claude Desktop configuration file:macOS:

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

Windows:

%APPDATA%/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Edit the configuration

Add the ČSFD MCP server to the mcpServers section:

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

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

Restart Claude Desktop

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

Verify the integration

Check if Claude can see the ČSFD tools by asking:

What tools do you have access to?

Claude should list the ČSFD tools including search, get_movie, get_creator, etc.

Complete Configuration Example

Here’s a full example of claude_desktop_config.json with the ČSFD server:

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

With multiple MCP servers:

{
  "mcpServers": {
    "csfd": {
      "command": "npx",
      "args": ["-y", "node-csfd-api", "mcp"]
    },
    "other-server": {
      "command": "node",
      "args": ["/path/to/other/server.js"]
    }
  }
}

Alternative Configuration (Local Build)

If you’ve cloned the repository and built it locally:

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

Using npx is recommended as it always pulls the latest version and doesn’t require manual installation.

Using ČSFD Data in Claude

Once configured, you can ask Claude to interact with ČSFD data naturally. Here are some example queries:

Example Queries

Search for movies

Query:

Search for "Pulp Fiction" on ČSFD and show me the rating

What happens:

Claude uses the search tool to find the movie
Extracts the ID from search results
Uses get_movie tool to get detailed information
Presents the rating and other details

Get creator information

Query:

Tell me about Quentin Tarantino's filmography on ČSFD

What happens:

Claude uses search to find Quentin Tarantino
Uses get_creator with his ID
Presents his biography and list of films with ratings

Find top-rated films

Query:

Find Christopher Nolan's top 5 highest-rated movies on ČSFD

What happens:

Searches for Christopher Nolan
Gets his creator profile with filmography
Sorts films by rating
Returns top 5 with titles, years, and ratings

Compare user ratings

Query:

What are the latest movie ratings from ČSFD user 912?

What happens:

Uses get_user_ratings with user ID 912
Retrieves recent ratings
Presents a list of rated movies with scores

Analyze reviews

Query:

Show me reviews from user 195357-verbal and summarize their taste

What happens:

Uses get_user_reviews to fetch reviews
Analyzes review text and ratings
Provides insights about the user’s preferences

Cinema screenings

Query:

What movies are playing in Prague today?

What happens:

Uses get_cinemas with district “Praha” and period “today”
Returns list of cinemas and their current screenings
Includes showtimes and movie details

Advanced Workflows

Multi-step Analysis

Claude can chain multiple tools together for complex queries: Query:

Find movies directed by Denis Villeneuve, show their ČSFD ratings, 
and tell me which one is most popular among Czech audiences.

Claude’s approach:

Uses search to find Denis Villeneuve
Uses get_creator to get his filmography
For each film, potentially uses get_movie to get detailed ratings
Compares ratings and vote counts
Provides analysis of the most popular film

Comparative Analysis

Query:

Compare the ratings of all Quentin Tarantino films on ČSFD 
and identify his most and least appreciated works.

Claude’s approach:

Searches for Tarantino
Gets his complete filmography
Analyzes rating distribution
Identifies top and bottom rated films
Provides insights about reception trends

User Preference Matching

Query:

Look at user 912's ratings and recommend similar movies they haven't rated yet.

Claude’s approach:

Gets user ratings with get_user_ratings
Identifies patterns (genres, directors, themes)
Searches for similar content
Cross-references to avoid duplicates
Provides personalized recommendations

Best Practices

Start with search

Always begin by searching for content rather than guessing IDs:

First search for "Inception" to get its ID, then show me the details

Be specific with requests

Provide context to help Claude choose the right tools:

Get the ČSFD rating for the 2010 sci-fi film Inception directed by Christopher Nolan

Request summaries for large data

When fetching many results, ask for summaries:

Get user 912's ratings and summarize their top 10 favorite films

Use filters when available

Take advantage of filtering parameters:

Get user ratings for ID 912, but only include films (exclude TV series and episodes)

Limitations and Considerations

The ČSFD MCP server scrapes live data from ČSFD.cz. Be respectful:

Avoid excessive requests in short time periods
Don’t use allPages: true for users with thousands of ratings
Consider caching results for repeated queries

Known Limitations

Rate limiting: ČSFD may block excessive requests
Data freshness: Data is scraped in real-time, so responses may be slower than APIs
Czech content focus: ČSFD is primarily focused on Czech/Slovak film database
No write operations: The tools are read-only (search and retrieve only)

Performance Tips

Use specific queries - “Get movie ID 535121” is faster than “Search for movies about…” then getting details
Limit pagination - Fetch specific pages instead of using allPages
Add delays - When fetching multiple pages, use allPagesDelay: 2000
Cache results - If you need to reference the same data multiple times, ask Claude to remember it in context

Troubleshooting

Claude doesn’t see the tools

Problem: Claude responds “I don’t have access to ČSFD data” Solutions:

Verify the config file path is correct
Check JSON syntax (use a JSON validator)
Restart Claude Desktop
Check if Node.js is in your PATH: node --version

Tools return errors

Problem: Claude shows tool execution errors Solutions:

Verify internet connection
Check if ČSFD.cz is accessible from your location
Try with a different search query or ID
Look at Claude’s detailed error message for specific issues

Slow responses

Problem: Queries take a long time to complete Solutions:

This is normal for scraping - data is fetched in real-time
Avoid using allPages parameter
Be more specific with queries to reduce tool calls
Check your internet connection speed

”Command not found” error

Problem: Claude shows npx or node command not found Solutions:

Ensure Node.js is installed: node --version
Add Node.js to your system PATH

Use absolute path to node in config:

{
  "command": "/usr/local/bin/node",
  "args": ["/usr/local/bin/npx", "-y", "node-csfd-api", "mcp"]
}

Example Conversations

Movie Discovery

User: “What’s the highest-rated sci-fi movie from 2010 on ČSFD?” Claude: [Uses search and get_movie tools] “Based on ČSFD data, ‘Inception’ (2010) directed by Christopher Nolan has a rating of 86% with over 100,000 votes, making it one of the highest-rated sci-fi films from that year.”

Director Analysis

User: “How do Wes Anderson’s films perform on ČSFD?” Claude: [Searches for Wes Anderson, gets creator details] “Wes Anderson’s films are highly regarded on ČSFD. His top-rated works include:

Grand Budapest Hotel (2014) - 78%
Moonrise Kingdom (2012) - 75%
The Royal Tenenbaums (2001) - 73% His distinctive visual style appears to resonate well with Czech audiences.”

User Profile Analysis

User: “Analyze the movie taste of ČSFD user 912” Claude: [Gets user ratings and reviews] “User 912 (BART!) shows a preference for:

Critically acclaimed dramas and thrillers
International cinema beyond Hollywood
Documentaries about nature and society
Average rating given: 3.8/5 stars They tend to appreciate thoughtful, well-crafted films over mainstream blockbusters.”

Next Steps

Available Tools

Learn about all MCP tools in detail

MCP Server Setup

Advanced server configuration

API Reference

Full API documentation

GitHub

View source and contribute

Core API

TypeScript Types

REST API

MCP Server

Claude Desktop Integration

Prerequisites

Configuration

Complete Configuration Example

Alternative Configuration (Local Build)

Using ČSFD Data in Claude

Example Queries

Advanced Workflows

Multi-step Analysis

Comparative Analysis

User Preference Matching

Best Practices

Limitations and Considerations

Known Limitations

Performance Tips

Troubleshooting

Claude doesn’t see the tools

Tools return errors

Slow responses

”Command not found” error

Example Conversations

Movie Discovery

Director Analysis

User Profile Analysis

Next Steps

Available Tools

MCP Server Setup

API Reference

GitHub

Build docs developers (and LLMs) love

Core API

TypeScript Types

REST API

MCP Server

​Prerequisites

​Configuration

​Complete Configuration Example

​Alternative Configuration (Local Build)

​Using ČSFD Data in Claude

​Example Queries

​Advanced Workflows

​Multi-step Analysis

​Comparative Analysis

​User Preference Matching

​Best Practices

​Limitations and Considerations

​Known Limitations

​Performance Tips

​Troubleshooting

​Claude doesn’t see the tools

​Tools return errors

​Slow responses

​”Command not found” error

​Example Conversations

​Movie Discovery

​Director Analysis

​User Profile Analysis

​Next Steps

Available Tools

MCP Server Setup

API Reference

GitHub

Build docs developers (and LLMs) love

Prerequisites

Configuration

Complete Configuration Example

Alternative Configuration (Local Build)

Using ČSFD Data in Claude

Example Queries

Advanced Workflows

Multi-step Analysis

Comparative Analysis

User Preference Matching

Best Practices

Limitations and Considerations

Known Limitations

Performance Tips

Troubleshooting

Claude doesn’t see the tools

Tools return errors

Slow responses

”Command not found” error

Example Conversations

Movie Discovery

Director Analysis

User Profile Analysis

Next Steps