Skip to main content
Glama

๐ŸŽฌ BookMyShow MCP Webscraper

Python Version FastAPI MCP Server License Tests

A Python scraper and API wrapper for BookMyShow that extracts movie listings, theater showtimes, ticket prices, and venue location details (including GPS latitude and longitude).

It packages everything into a FastAPI REST server, MCP tools (for AI assistants like Claude or Cursor), a CLI tool, and a built-in web dashboard.


โœจ Features

  • Lists Movies & Events: Gets active or upcoming movie listings across Indian cities (Mumbai, Delhi-NCR, Bengaluru, Chennai, etc.), with filters for language and genre.

  • Fetches Showtimes & Pricing: Pulls cinema showtimes, screen formats (2D, 3D, IMAX, 4DX), ticket price ranges (in โ‚น), and seat availability.

  • Extracts Venue Locations & Lat/Long: Pulls theater street addresses, exact latitude and longitude coordinates, and venue amenities (parking, food court, M-ticket entry).

  • Gets Movie Synopsis & Trailers: Retrieves plot summaries, cast and crew info, ratings, posters, and YouTube trailer links.

  • Runs as an MCP Server: Works out-of-the-box with AI tools (Claude Desktop, Cursor, Antigravity) via bms-mcp (or mcp_server.py locally).

  • FastAPI REST Server: Interactive Swagger API docs (/docs).

  • Terminal CLI: Terminal interface for search, listings, and exports.

  • Exports to Files: Exports scraped data to JSON, CSV, or Excel (.xlsx).

  • Web Dashboard: Simple light-theme dashboard to browse movies and test endpoints.


Related MCP server: Movie Booking Assistant

๐Ÿš€ Quickstart & Installation

git clone https://github.com/m0han-r/bookmyshow-mcp-webscraper.git
cd bookmyshow-mcp-webscraper
pip install -r requirements.txt

๐Ÿ”Œ API & MCP Tools

REST Endpoint

MCP Tool Name

Parameters

Description

GET /api/v1/cities

bms_get_cities

popular_only

Supported Indian regions & popular cities

GET /api/v1/movies

bms_get_movies

city, language, genre

Active movie listings with language/genre filters

GET /api/v1/events

bms_get_events

city, category

Live events, comedy shows, music concerts, and sports

GET /api/v1/movies/{code}

bms_get_movie_details

movie_code, city

Synopsis, cast, crew, ratings, poster & trailer links

GET /api/v1/showtimes

bms_get_showtimes

movie_code, city, date, language, format

Showtimes, screen formats (IMAX/3D/4DX), prices, seats & language filtering

GET /api/v1/venues/{code}

bms_get_venue_details

venue_code, city

Cinema street address, exact latitude, longitude & facilities

GET /api/v1/search

bms_search

query, city

Cross-search movies and live events

Sample Venue Response (GET /api/v1/venues/PCAN?city=chennai):

{
  "success": true,
  "count": 1,
  "data": {
    "venue_code": "PCAN",
    "venue_name": "PVR: VR Chennai, Anna Nagar",
    "address": "3rd Floor, VR Mall, Metro Zone, Jawaharlal Nehru Road, Anna Nagar, Chennai, Tamil Nadu 600040",
    "latitude": 13.082561,
    "longitude": 80.194803,
    "facilities": ["Ticket Cancellation", "F&B", "MTicket", "Parking Facility", "Food Court"]
  }
}

๐ŸŒ Running the REST API Server

Start the server:

python main.py

๐Ÿค– MCP Server Setup

Connect your AI assistant (Claude Desktop, Cursor, Antigravity) using uvx. uvx automatically fetches the package from GitHub and executes the bms-mcp script entry point registered in pyproject.toml.

Claude Desktop / Cursor / Antigravity Configuration

Add to your %APPDATA%\Claude\claude_desktop_config.json (or .cursor/mcp.json):

{
  "mcpServers": {
    "bookmyshow": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git",
        "bms-mcp"
      ]
    }
  }
}

Direct Terminal Execution

Run natively in PowerShell or Command Prompt (uv generates and runs bms-mcp.exe wrappers on Windows):

uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-mcp

Claude Desktop / Cursor / Antigravity Configuration

Add to your ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bookmyshow": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git",
        "bms-mcp"
      ]
    }
  }
}

Direct Terminal Execution

Run directly in Linux Terminal:

uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-mcp

Claude Desktop / Cursor / Antigravity Configuration

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bookmyshow": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git",
        "bms-mcp"
      ]
    }
  }
}

Direct Terminal Execution

Run directly in macOS Terminal / zsh:

uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-mcp

If you have cloned the repository locally:

python mcp_server.py

๐Ÿ Python Usage

from bms_scraper import BookMyShowScraper

scraper = BookMyShowScraper()

# Get active movies
movies = scraper.get_movies(city="mumbai", language="Hindi")

# Get venue coordinates
venue = scraper.get_venue_details(venue_code_or_url="PCAN", city="chennai")
print(f"๐Ÿ“ {venue.venue_name} - Lat: {venue.latitude}, Lon: {venue.longitude}")

# Get showtimes (supports language filters e.g. "tamil", "hindi", "all" and format filters e.g. "IMAX", "2D")
showtimes = scraper.get_showtimes(movie_code_or_url="ET00378770", city="chennai", date="20260827", language="tamil", format="2D")

๐Ÿ’ป CLI Usage

Execute the CLI directly via uvx without installing dependencies, or locally via Python:

# List popular cities via uvx
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli cities --popular

# Scrape movies in Bengaluru and export to Excel
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli movies --city bengaluru --language Hindi --export xlsx

# Scrape showtimes in Chennai for Tamil language with date and export to JSON
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli showtimes --code ET00378770 --city chennai --date 20260827 --language tamil --export json
# List popular cities via uvx
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli cities --popular

# Scrape movies in Bengaluru and export to Excel
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli movies --city bengaluru --language Hindi --export xlsx

# Scrape showtimes in Chennai for Tamil language with date and export to JSON
uvx --from git+https://github.com/m0han-r/bookmyshow-mcp-webscraper.git bms-cli showtimes --code ET00378770 --city chennai --date 20260827 --language tamil --export json
# List popular cities
python -m bms_scraper.cli cities --popular

# Scrape movies in Bengaluru and export to Excel
python -m bms_scraper.cli movies --city bengaluru --language Hindi --export xlsx

# Scrape showtimes with language filter
python -m bms_scraper.cli showtimes --code ET00378770 --city chennai --date 20260827 --language tamil --format 2D

๐Ÿ“Š Exporting Data

from bms_scraper import BookMyShowScraper, DataExporter

scraper = BookMyShowScraper()
movies = scraper.get_movies(city="mumbai")

DataExporter.to_csv(movies, "movies.csv")
DataExporter.to_excel(movies, "movies.xlsx")
DataExporter.to_json(movies, "movies.json")

๐Ÿงช Running Tests

python -m pytest

โš–๏ธ License

Distributed under the MIT License.

Available Tools

7 tools
bms_get_citiesA

Get Supported Cities & Regions

Returns all supported regions and major popular cities across India on BookMyShow (Mumbai, Delhi-NCR, Bengaluru, Hyderabad, Chennai, Pune, Kolkata, etc.) with region codes and URL slugs.

Args: popular_only: If True, returns only major popular tier-1 metropolitan cities.

Inputs: popular_only. Returns: result

bms_get_eventsA

Get Live Events & Shows in a City

Retrieves active live events, comedy standup shows, music concerts, sports matches, exhibitions, and workshops in a target city with venue names, event dates, and category tags.

Args: city: City slug (e.g. 'mumbai', 'bengaluru', 'delhi'). category: Event category filter ('events', 'comedy-shows', 'music-shows', 'sports').

Inputs: city, category. Returns: result

bms_get_movie_detailsA

Get Movie Synopsis & Metadata

Retrieves comprehensive movie metadata including full plot synopsis, duration, censor certification, ratings, audio languages, high-res poster and banner background URLs, cast and crew profiles, and official video trailer links.

Args: movie_code: BookMyShow movie event code (e.g. 'ET00378770') or full movie page URL. city: City slug (default 'mumbai').

Inputs: movie_code (required), city. Returns: result

bms_get_moviesA

Get Active Movie Listings in a City

Retrieves clean, structured movie listings currently showing or coming soon in a selected city, with optional filtering by audio language (Hindi, English, Tamil, Telugu, Kannada) and genre (Action, Comedy, Drama, Thriller).

Args: city: City slug (e.g. 'mumbai', 'bengaluru', 'national-capital-region-ncr', 'hyderabad', 'chennai'). language: Filter by language (e.g. 'Hindi', 'English', 'Tamil', 'Telugu'). genre: Filter by genre (e.g. 'Action', 'Drama', 'Comedy', 'Thriller').

Inputs: city, genre, language. Returns: result

bms_get_showtimesA

Get Cinema Venues & Showtimes

Retrieves all cinema halls/theaters showing a specific movie in a city, including showtimes, screen formats (2D, 3D, IMAX 3D, 4DX, ICE), ticket price ranges in INR, mobile ticket entry support (is_m_ticket), and seat availability status.

Args: movie_code: Movie event code (e.g. 'ET00378770') or full BookMyShow buy tickets URL. city: City slug (e.g. 'mumbai', 'chennai', 'bengaluru'). date: Show date in YYYYMMDD format (e.g. '20260826') or YYYY-MM-DD. Defaults to current date. language: Language filter or 'all' to aggregate all languages (e.g. 'tamil', 'hindi', 'kannada', 'telugu', 'all'). format: Screen format filter (e.g. '2D', '3D', 'IMAX', '4DX', 'EPIQ', 'ICE').

Inputs: movie_code (required), city, date, format, +1 more. Returns: result

bms_get_venue_detailsA

Get Cinema Venue Location & Geo Coordinates

Retrieves detailed cinema hall/theater metadata including full street address, landmark, postal code, exact latitude and longitude coordinates, and available venue facilities/amenities (Parking, F&B, M-Ticket, Ticket Cancellation, Food Court).

Args: venue_code: BookMyShow venue code (e.g. 'PCAN', 'CSWO') or full venue URL. city: City slug (e.g. 'chennai', 'mumbai').

Inputs: venue_code (required), city. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a unique resource and action: cities, movie listings, event listings, specific movie details, showtimes for a movie in a city, cross-search, and venue details. There is no overlap in purpose, and even the search tool is distinct from the listing tools.

    Naming Consistency5/5

    All tools follow a consistent `bms_` prefix with `get_` verb for most, and one `search` exception that still fits a clear pattern. The naming is predictable and uniform across the set.

    Tool Count5/5

    7 tools is well-scoped for a movie/event discovery API. Each tool covers a distinct aspect of browsing, from city selection to venue details, without unnecessary redundancy or overwhelming count.

    Completeness4/5

    The tool surface covers core browsing workflows (cities, listings, details, showtimes, venues, search), but there is a notable gap: detailed information for live events (only listing is available, no event-specific details like movie_details). This is a minor gap that agents could work around using the listing data.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides a comprehensive movie booking experience for AMC Theatres, enabling users to discover movies, find showtimes, select seats, and process payments through conversational AI. Supports multi-location theater search with real-time seat availability and booking management.
      6
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides a comprehensive movie booking experience for AMC Theatres, enabling conversational AI assistants to help users discover movies, find showtimes, book seats, and process payments.
      6
      MIT