bms-mcp
Provides tools for searching movies, events, showtimes, and venue details, including ticket price ranges, seat availability, addresses, and GPS coordinates on BookMyShow.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bms-mcp What movies are playing in Mumbai this weekend?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ฌ BookMyShow MCP Webscraper
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(ormcp_server.pylocally).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 |
|
|
| Supported Indian regions & popular cities |
|
|
| Active movie listings with language/genre filters |
|
|
| Live events, comedy shows, music concerts, and sports |
|
|
| Synopsis, cast, crew, ratings, poster & trailer links |
|
|
| Showtimes, screen formats (IMAX/3D/4DX), prices, seats & language filtering |
|
|
| Cinema street address, exact latitude, longitude & facilities |
|
|
| 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.pySwagger UI: http://localhost:8000/docs
Web Dashboard: http://localhost:8000/
๐ค 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-mcpClaude 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-mcpClaude 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-mcpIf 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 toolsbms_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
bms_searchA
Search Movies & Live Events
Performs a cross-search across active movie titles and live event listings in a selected city matching a query search term.
Args: query: Search query keyword (e.g. 'Toxic', 'Standup Comedy'). city: City slug (e.g. 'mumbai', 'bengaluru').
Inputs: query (required), city. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Movie Planner MCP: watchlists, showtimes, tracked cinema ticket links.
Booking gateway for AI agents โ discover events, movies & hotels, hand off to partner checkout.
Live Google Maps business search, review, and photo data for AI agents over MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides 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.61MIT
- FlicenseNot gradedqualityDmaintenanceProvides a suite of tools for searching movies, checking showtimes, and managing ticket bookings for Bangalore cinemas. It enables AI clients to handle end-to-end movie theater interactions including seat availability checks and reservation management.-
- FlicenseNot gradedqualityDmaintenanceEnables searching for movies, checking Google Calendar for conflicts, and booking tickets with seat type and INR pricing, all through natural conversation. Supports demo mode without API keys.-
- AlicenseAqualityDmaintenanceProvides a comprehensive movie booking experience for AMC Theatres, enabling conversational AI assistants to help users discover movies, find showtimes, book seats, and process payments.6MIT