cineplex-mcp

cineplex-mcp

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

This is a personal-use tool, not a commercial product. Cineplex has noofficial partner API for this data; this server calls Cineplex'sundocumented public web endpoints directly. It's built to cacheaggressively, keep request volume low, and fail gracefully rather thanpretend 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.comendpoints, tested end-to-end against real responses as of 2026-07-19. SeeCAPTURE.md for how they were found and what to do ifCineplex changes something in the future (e.g. rotates the theatrical API'ssubscription key).

Setup

npm install

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

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

Running

npm start

This starts the MCP server on stdio, for use by an MCP client (ClaudeDesktop, Claude Code, etc.) — it's not meant to be run standalone forinteractive 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'scurrent 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 substringmatch — also works for "IMAX 70mm", "UltraAVX", "Dolby", etc.),scored for seat quality. Returns both the full scored list and anoptimal subset.
• get_optimal_seats — { theatreId, showtimeId, excludeFrontRows?, excludeSideSeats?, minContiguous? } → seat score for a single already-knownshowtime. 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 IDsare numeric, and find_theatres/find_optimal_showtimes hand them back asnumbers, so chaining one tool's output straight into the next one's inputjust works.

Seat-quality parameters

• excludeFrontRows (default 3): drop this many front rows entirely.
• excludeSideSeats (default 3): trim this many seats from each side ofevery remaining row (by position, not raw seat number, so aisle gapsdon't cause off-by-N errors).
• minContiguous (default 1): require a contiguous block of at leastthis 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-20with 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 asynthetic 10-row, 12-seat auditorium, covering front-row exclusion,side-seat exclusion with row gaps, contiguous-run detection, and theminContiguous 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 plumbingin cineplexClient.js is confirmed working end-to-end. A CineplexApiErrorhere means something changed upstream — see CAPTURE.md's "If this breaksin 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 normalizedform. normalizeCineplexSeatMap() in cineplexClient.js is the soleadapter between the two, so a future Cineplex response-shape change (or afuture non-Cineplex chain) only requires a new adapter, not scoringchanges.

Non-goals (v1)

• No ticket purchasing — read-only lookups only. Pricing itself isn't evenfetched; 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; seatavailability is never cached, since it changes as people book/abandoncarts).
• No login/auth flows. Every endpoint this server calls was confirmed towork without one.

License

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