Filmladder MCP Server
A Model Context Protocol (MCP) server that provides movie listings and recommendations for Amsterdam cinemas by scraping filmladder.nl.
Features
- List Movies: Get all movies playing in Amsterdam cinemas, optionally filtered by date
- Get Showtimes: Find all showtimes for a specific movie (with fuzzy title matching)
- Cinema Movies: List all movies playing at a specific cinema
- Recommendations: Get movie recommendations based on rating, preferred showtimes, cinemas, and date
Requirements
- Python 3.11 or higher
- Poetry for dependency management
Installation
-
Clone the repository:
git clone <repository-url> cd filmladder-mcp -
Install dependencies using Poetry:
poetry install -
Install pre-commit hooks (optional but recommended):
poetry run pre-commit install -
Copy
.env.exampleto.envand adjust configuration if needed:cp .env.example .env
Usage
Running the MCP Server
The server uses stdio transport and can be run directly:
poetry run python -m src.server
Connecting to Cursor IDE
To use this MCP server in Cursor:
-
Project-specific configuration (recommended):
- The project includes a
.cursor/mcp.jsonfile with the server configuration - Cursor should automatically detect it when you open this project
- The project includes a
-
Manual configuration:
- Open Cursor Settings (gear icon)
- Go to Tools & Integrations → MCP Tools
- Click Add Custom MCP or edit
mcp.json - Add the following configuration:
{ "mcpServers": { "filmladder-mcp": { "command": "poetry", "args": ["run", "python", "-m", "src.server"], "cwd": "/path/to/filmladder-mcp" } } }Important: Replace
/path/to/filmladder-mcpwith the actual path to this project directory. -
Verify connection:
- After saving, Cursor should show "filmladder-mcp" in the MCP Tools section
- You can test it by asking Cursor: "What movies are playing in Amsterdam today?"
Using the MCP Tools in Cursor
Once connected, you can use the tools in Cursor's chat:
- List movies: "What movies are playing in Amsterdam?"
- Get showtimes: "When is Nuremberg playing?"
- Cinema movies: "What movies are playing at Pathé Tuschinski?"
- Recommendations: "Recommend me a movie with rating above 7.0 for tonight"
MCP Tools
The server exposes the following tools:
list_movies
List all movies playing in Amsterdam cinemas.
Parameters:
date(optional): Date filter in YYYY-MM-DD format
Example:
{
"date": "2025-01-15"
}
get_showtimes
Get all showtimes for a specific movie (fuzzy matching on title).
Parameters:
movie_title(required): Title of the movie
Example:
{
"movie_title": "Nuremberg"
}
list_cinema_movies
List all movies playing at a specific cinema.
Parameters:
cinema_name(required): Name of the cinema
Example:
{
"cinema_name": "Pathé Tuschinski"
}
recommend_movies
Recommend movies based on various criteria.
Parameters:
min_rating(optional): Minimum rating threshold (default: 0.0)preferred_times(optional): Array of preferred showtimes in HH:MM formatpreferred_cinemas(optional): Array of preferred cinema namesdate(optional): Target date for recommendations in YYYY-MM-DD format
Example:
{
"min_rating": 7.0,
"preferred_times": ["20:00", "21:00"],
"preferred_cinemas": ["Pathé Tuschinski", "EYE"],
"date": "2025-01-15"
}
Testing
Unit Tests
Run the test suite:
poetry run pytest tests/
Run with verbose output:
poetry run pytest tests/ -v
Quick Server Test
Test that the server initializes correctly:
poetry run python test_server.py
This will verify that:
- The server can be imported
- Tools are registered correctly
- Basic functionality works
Testing with MCP Inspector
The recommended way to test the full MCP server is using the MCP Inspector:
-
Install MCP Inspector (if not already installed):
npm install -g @modelcontextprotocol/inspector -
Run the inspector:
npx @modelcontextprotocol/inspector -
Configure the inspector to use your server:
- Server command:
poetry run python -m src.server - Transport: stdio
- Server command:
-
The inspector will provide an interactive interface to test all tools.
Manual Testing
You can also test the server manually by running it and sending JSON-RPC messages via stdin:
poetry run python -m src.server
Then send initialization and tool call requests in JSON-RPC format.
Development
Code Quality
This project uses:
- ruff for linting and import sorting
- black for code formatting
- mypy for type checking
- pre-commit hooks to ensure code quality
- pytest for testing
Run linting and formatting:
poetry run ruff check src/
poetry run black src/
poetry run mypy src/
Run tests:
poetry run pytest tests/
Project Structure
filmladder-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── scraper.py # Web scraping logic
│ ├── models.py # Pydantic data models
│ ├── config.py # Pydantic-settings configuration
│ └── recommender.py # Recommendation logic
├── pyproject.toml # Poetry dependencies and project config
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── .cursorrules # Cursor IDE rules
├── README.md # This file
└── .env.example # Example environment variables
Type Annotations
All code must use type annotations. The project follows Python 3.11+ type hinting conventions:
- Use
list[T]instead ofList[T] - Use
str | Noneinstead ofOptional[str] - All functions, methods, and variables must be typed
Pydantic Models
All data structures use Pydantic BaseModel for validation and serialization. Configuration uses pydantic-settings for environment variable support.
Error Handling
The server handles:
- Network errors (HTTP timeouts, connection failures)
- Parsing errors (HTML structure changes)
- Invalid input parameters
Errors are raised as exceptions that the MCP framework will handle appropriately.
License
[Add your license here]
Contributing
[Add contributing guidelines here]
