cineplex-mcp

An MCP (Model Context Protocol) server that lets Claude look up Cineplex Canada showtimes and find ones with good seats available — e.g. "Find showtimes for The Odyssey in IMAX 70mm near me with good seats, not the first 3 rows, not on the sides."

This is a personal-use tool, not a commercial product. Cineplex has no official partner API for this data; this server calls Cineplex's undocumented public web endpoints directly. It's built to cache aggressively, keep request volume low, and fail gracefully rather than pretend otherwise. See cineplex-mcp-PRD.md for the full design rationale.

Status: all four Cineplex data endpoints are confirmed working

All four calls this server depends on hit real, live apis.cineplex.com endpoints, tested end-to-end against real responses as of 2026-07-19. See CAPTURE.md for how they were found and what to do if Cineplex changes something in the future (e.g. rotates the theatrical API's subscription key).

Setup

npm install

Node.js 18+ is required (for built-in fetch).

No environment variables or session tokens are required — every endpoint this server calls was confirmed to work unauthenticated (theatre/movie/ showtime discovery uses a static, public subscription key baked into cineplexClient.js; seat data needs no key at all). See CAPTURE.md if that ever changes.

Running

npm start

This starts the MCP server on stdio, for use by an MCP client (Claude Desktop, Claude Code, etc.) — it's not meant to be run standalone for interactive use.

Claude Desktop configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "cineplex": {
      "command": "node",
      "args": ["/absolute/path/to/cineplex-mcp/src/index.js"]
    }
  }
}

Restart Claude Desktop after editing the config.

Claude Code configuration

claude mcp add cineplex -- node /absolute/path/to/cineplex-mcp/src/index.js

Tools exposed

• find_theatres — { lat, lon, rangeKm? } → nearby theatres (id, name, address, distance), sorted by distance.
• find_movie — { title } → best fuzzy match against Cineplex's current movie catalog, including the Cineplex movie ID.
• find_optimal_showtimes — { movieTitle, theatreId, date, formatMatch?, excludeFrontRows?, excludeSideSeats?, minContiguous? } → showtimes matching a format (default "IMAX", case-insensitive substring match — also works for "IMAX 70mm", "UltraAVX", "Dolby", etc.), scored for seat quality. Returns both the full scored list and an optimal subset.
• get_optimal_seats — { theatreId, showtimeId, excludeFrontRows?, excludeSideSeats?, minContiguous? } → seat score for a single already-known showtime. Cineplex's seat endpoints are keyed by the (theatreId, showtimeId) pair, not showtimeId alone.

theatreId/showtimeId accept either a string or a number — Cineplex's IDs are numeric, and find_theatres/find_optimal_showtimes hand them back as numbers, so chaining one tool's output straight into the next one's input just works.

Seat-quality parameters

• excludeFrontRows (default 3): drop this many front rows entirely.
• excludeSideSeats (default 3): trim this many seats from each side of every remaining row (by position, not raw seat number, so aisle gaps don't cause off-by-N errors).
• minContiguous (default 1): require a contiguous block of at least this many available seats — set to 2 for a couple, 4 for a group, etc.

Example prompts

• "Find theatres near me at lat 43.65, lon -79.38."
• "Look up the movie 'The Odyssey' on Cineplex."
• "Find IMAX 70mm showtimes for The Odyssey at theatre 9806 on 2026-07-20 with good seats, not the first 3 rows or within 3 seats of the wall."
• "Same as above but I need 2 seats together for me and my partner."

Testing

Unit tests (no network required)

npm test

Runs test/seatScoring.test.js (Node's built-in test runner) against a synthetic 10-row, 12-seat auditorium, covering front-row exclusion, side-seat exclusion with row gaps, contiguous-run detection, and the minContiguous parameter.

Manual smoke test (live endpoints)

node -e "
import('./src/cineplexClient.js').then(async (c) => {
  const theatres = await c.getTheatres({ lat: 43.6532, lon: -79.3832, rangeKm: 25 });
  console.log('theatres found:', theatres.length, theatres[0]);

  const movie = await c.findMovieByTitle('Dune');
  console.log('best movie match:', movie);
});
"

If this returns real data, the caching/throttling/error-handling plumbing in cineplexClient.js is confirmed working end-to-end. A CineplexApiError here means something changed upstream — see CAPTURE.md's "If this breaks in the future" section.

Architecture

src/
  index.js           # MCP server entrypoint; registers tools, thin glue only
  cineplexClient.js   # All HTTP calls to Cineplex's API; caching + throttling
  seatScoring.js       # Pure functions: normalized seat map -> score. No
                        # network calls, no Cineplex-specific knowledge.
CAPTURE.md            # Record of how the live endpoints were found, and how
                        # to re-capture them if something changes

seatScoring.js never sees Cineplex's raw JSON shape — only the normalized form. normalizeCineplexSeatMap() in cineplexClient.js is the sole adapter between the two, so a future Cineplex response-shape change (or a future non-Cineplex chain) only requires a new adapter, not scoring changes.

Non-goals (v1)

• No ticket purchasing — read-only lookups only. Pricing itself isn't even fetched; Cineplex doesn't expose it outside its login-gated checkout flow.
• No chains other than Cineplex.
• No persistent database — in-memory cache only (process lifetime; seat availability is never cached, since it changes as people book/abandon carts).
• No login/auth flows. Every endpoint this server calls was confirmed to work without one.

License

MIT — see LICENSE. This remains an unofficial, personal-use tool built against Cineplex's undocumented endpoints; see the disclaimer at the top of this file and in cineplex-mcp-PRD.md before relying on it for anything beyond that.