FDFS BookMyShow MCP Server

A specialized Model Context Protocol (MCP) server for searching movies and theaters on BookMyShow using web scraping with Puppeteer.

Overview

This MCP server provides AI agents with the ability to search for movies and theaters on BookMyShow, India's leading entertainment ticketing platform. It uses Puppeteer to bypass Cloudflare protection and scrape real-time data.

Features

• Movie Search: Find movies by title with details like genre, language, duration, and ratings
• Theater Search: Search for specific theaters by name within a region
• Theater Listings: Get comprehensive lists of theaters in specific regions
• Region Code Lookup: Find BookMyShow region codes for different cities
• Now Showing Movies: Get current movies playing in theaters with showtimes and booking details
• Upcoming Movies: Discover upcoming movie releases with trailers, cast, and advance booking options
• Cloudflare Bypass: Uses Puppeteer with stealth techniques to access BookMyShow data

Available Tools

🎬 Movie Search

• Tool: movies_search
• Description: Search for movies on BookMyShow
• Parameters:
  • query (string): Movie name or keyword to search for
  • limit (number, optional): Maximum results to return (1-20, default: 10)

🎭 Theater Search

• Tool: theaters_search
• Description: Search for specific theaters by name within a region
• Parameters:
  • query (string): Theater/cinema name to search for
  • regionCode (string): Region code (e.g., 'MUMBAI', 'VIZA')
  • limit (number, optional): Maximum results to return (1-20, default: 10)

🏢 Theater Listings

• Tool: theaters_list
• Description: List all theaters in a specific region
• Parameters:
  • regionCode (string): Region code to list theaters for
  • limit (number, optional): Maximum results to return (1-20, default: 10)

📍 Region Code Lookup

• Tool: region_code
• Description: Find BookMyShow region codes by region name
• Parameters:
  • regionName (string): Region name to search for (e.g., 'vizag', 'mumbai', 'delhi')

🎥 Now Showing Movies

• Tool: now_showing
• Description: Get movies currently showing in a specific region
• Parameters:
  • regionCode (string): Region code (e.g., 'HYD', 'MUMBAI')
  • pageId (number): Page number for pagination (1-10)

🎬 Upcoming Movies

• Tool: upcoming_movies
• Description: Get upcoming movies in a specific region with release dates and details
• Parameters:
  • regionCode (string): Region code (e.g., 'HYD', 'MUMBAI')
  • pageId (number): Page number for pagination (1-10)
  • lat (number, optional): Latitude coordinate for location-based results
  • lon (number, optional): Longitude coordinate for location-based results

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/FDFS-mcp.git
   cd FDFS-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

STDIO Mode (recommended for MCP clients)

npm run start:stdio

HTTP Mode (for API access)

npm run start:http

Development Mode

npm run dev:stdio  # STDIO with auto-reload
npm run dev:http   # HTTP with auto-reload

Configuration

The server can be configured through environment variables:

# Transport Configuration
MCP_TRANSPORT_TYPE=stdio  # or "http"
MCP_HTTP_PORT=3000        # for HTTP mode
MCP_HTTP_HOST=localhost   # for HTTP mode

# Logging
MCP_LOG_LEVEL=debug       # debug, info, warn, error
LOGS_DIR=./logs          # log directory

# Environment
NODE_ENV=development      # or "production"

Integration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "bookmyshow": {
      "command": "node",
      "args": ["path/to/FDFS-mcp/dist/index.js"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Using MCP Inspector

For debugging and testing:

npm run inspector

Example Queries

Search for Movies

Search for "Avatar" movies on BookMyShow

Find Theaters

Find theaters in Mumbai region

Search Specific Theater

Search for "PVR" theaters in Hyderabad

Get Region Code

What is the region code for Bangalore?

Project Structure

src/
├── index.ts                 # Main entry point
├── config/                  # Configuration management
├── mcp-server/             # MCP server implementation
│   ├── server.ts           # Server setup and initialization
│   ├── core/               # Core server components
│   ├── tools/              # Tool implementations
│   │   ├── movieSearch/    # Movie search functionality
│   │   ├── regionCode/     # Region code lookup
│   │   ├── theaterSearch/  # Theater search functionality
│   │   └── theatersList/   # Theater listing functionality
│   └── transports/         # Transport layer (HTTP/STDIO)
├── types-global/           # Global type definitions
└── utils/                  # Utility functions
    ├── internal/           # Error handling, logging
    ├── network/            # Network utilities
    ├── parsing/            # Data parsing utilities
    └── security/           # Security and sanitization

Development

Building

npm run build

Type Checking

npm run typecheck

Linting

npm run lint
npm run lint:fix

Formatting

npm run format

Technical Details

• Language: TypeScript
• Runtime: Node.js >=20.0.0
• Web Scraping: Puppeteer with stealth techniques
• Protocol: Model Context Protocol (MCP) 2025-06-18 specification
• Transports: STDIO and HTTP supported
• Error Handling: Comprehensive error categorization and logging

License

Apache 2.0 - see LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub
• Check the logs in the logs/ directory for debugging information

Built with ❤️ for the MCP ecosystem and BookMyShow integration.