AMC MCP Server
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., "@AMC MCP Server find showtimes for Dune: Part Two in Boston tonight"
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.
AMC MCP Server š¬
An Model Context Protocol (MCP) server that provides a comprehensive movie booking experience for AMC Theatres. This server enables conversational AI assistants to help users discover movies, find showtimes, book seats, and process payments through a simple API interface.
Features āØ
Movie Discovery: Browse currently showing movies and get personalized recommendations
Showtime Lookup: Find available showtimes by location, date, and movie
Seat Selection: View interactive seat maps and check availability
Booking Management: Reserve seats with real-time availability checking
Payment Processing: Handle mock payment transactions with confirmation receipts
Multi-location Support: Search across multiple AMC theater locations
Related MCP server: AMC MCP Server
Quick Start š
Prerequisites
Python 3.8+
Docker (optional, for containerized deployment)
Installation
Option 1: Local Installation
Clone the repository:
git clone <repository-url>
cd amc-mcpInstall dependencies:
pip install -r requirements.txtInstall the package:
pip install -e .Run the server:
python -m amc_mcp.fastmcp_serverOption 2: Docker Deployment
Build and run with Docker Compose:
docker-compose up --buildOr build and run manually:
docker build -t amc-mcp .
docker run -it amc-mcpMCP Tools Reference š ļø
1. get_now_showing
Returns a list of movies currently showing in a given location.
Input:
{
"location": "Boston, MA"
}Output:
{
"location": "Boston, MA",
"movies": [
{
"movie_id": "mv001",
"title": "Dune: Part Two",
"rating": "PG-13",
"duration": 166,
"genre": "Sci-Fi/Action",
"description": "Paul Atreides unites with Chani..."
}
]
}2. get_recommendations
Suggests movies based on mood, genre, or preferences.
Input:
{
"genre": "action",
"mood": "exciting"
}Output:
{
"criteria": {"genre": "action", "mood": "exciting"},
"recommendations": [...]
}3. get_showtimes
Fetches available showtimes for a specific movie and location.
Input:
{
"movie_id": "mv001",
"date": "2025-10-28",
"location": "Boston, MA"
}Output:
{
"movie": {"id": "mv001", "title": "Dune: Part Two"},
"date": "2025-10-28",
"location": "Boston, MA",
"showtimes": [
{
"showtime_id": "st001",
"theater_name": "AMC Boston Common 19",
"theater_address": "175 Tremont Street",
"time": "14:00",
"format": "IMAX",
"price": 18.50
}
]
}4. get_seat_map
Displays available and reserved seats for a specific showtime.
Input:
{
"showtime_id": "st001"
}Output:
{
"showtime_id": "st001",
"movie": "Dune: Part Two",
"theater": "AMC Boston Common 19",
"date": "2025-10-28",
"time": "14:00",
"seat_map": [
{
"seat_number": "A5",
"row": "A",
"column": 5,
"is_available": true,
"price_tier": "Standard",
"price": 18.50
}
]
}5. book_seats
Reserves selected seats for the user.
Input:
{
"showtime_id": "st001",
"seats": ["A5", "A6"],
"user_id": "user123"
}Output:
{
"booking_id": "booking-uuid",
"status": "pending",
"movie": "Dune: Part Two",
"theater": "AMC Boston Common 19",
"date": "2025-10-28",
"time": "14:00",
"seats": ["A5", "A6"],
"total_price": 37.00
}6. process_payment
Handles simulated payment transaction.
Input:
{
"booking_id": "booking-uuid",
"payment_method": "card",
"amount": 37.00
}Output:
{
"payment_id": "payment-uuid",
"payment_status": "success",
"booking_id": "booking-uuid",
"receipt_url": "https://amc.com/receipts/payment-uuid",
"confirmation": {
"movie": "Dune: Part Two",
"theater": "AMC Boston Common 19",
"date": "2025-10-28",
"time": "14:00",
"seats": ["A5", "A6"],
"total_paid": 37.00
}
}Example Conversation Flow š¬
Here's how a typical movie booking conversation would work:
User: "Find an action movie near me tonight."
Server calls:
get_now_showing+get_recommendationsReturns: List of action movies with showtimes
User: "Book two seats for Dune: Part Two at 8 PM."
Server calls:
get_showtimesāget_seat_mapābook_seatsReturns: Seat selection and booking confirmation
User: "Pay with my card."
Server calls:
process_paymentReturns: Payment confirmation with digital receipt
Architecture šļø
amc-mcp/
āāā src/
ā āāā amc_mcp/
ā āāā __init__.py
ā āāā server.py # Main MCP server implementation
āāā data/
ā āāā movies.json # Movie catalog
ā āāā theaters.json # Theater locations
ā āāā showtimes.json # Showtime schedules
ā āāā seats.json # Seat maps by showtime
āāā config/
ā āāā nginx.conf # Web server configuration
āāā Dockerfile # Container configuration
āāā docker-compose.yml # Multi-service orchestration
āāā requirements.txt # Python dependencies
āāā pyproject.toml # Package configuration
āāā README.md # This fileData Models š
Movie
{
"movie_id": str,
"title": str,
"rating": str, # PG, PG-13, R, etc.
"duration": int, # Minutes
"genre": str,
"description": str,
"poster_url": str
}Theater
{
"theater_id": str,
"name": str,
"address": str,
"city": str,
"state": str,
"zip_code": str
}Showtime
{
"showtime_id": str,
"movie_id": str,
"theater_id": str,
"date": str, # YYYY-MM-DD
"time": str, # HH:MM
"format": str, # Standard, IMAX, 3D, Dolby
"price": float
}Development šØāš»
Adding New Movies
Edit data/movies.json to add new movies:
{
"movie_id": "mv011",
"title": "New Movie Title",
"rating": "PG-13",
"duration": 120,
"genre": "Action",
"description": "Description of the movie...",
"poster_url": "https://example.com/poster.jpg"
}Adding New Theaters
Edit data/theaters.json:
{
"theater_id": "th011",
"name": "AMC New Location 15",
"address": "123 Main Street",
"city": "New City",
"state": "NY",
"zip_code": "12345"
}Adding Showtimes
Edit data/showtimes.json and data/seats.json to add new showtimes and corresponding seat maps.
Testing
Manual Testing
You can test individual tools using the MCP inspector or by connecting to any MCP-compatible client.
Testing with Claude Desktop
Configure Claude Desktop to connect to your MCP server
Use natural language to test the booking flow
Example: "Find me a sci-fi movie showing tonight in Boston"
Configuration āļø
Environment Variables
PYTHONPATH: Set to/app/srcfor proper module resolutionPYTHONUNBUFFERED: Set to1for real-time loggingMCP_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
Docker Configuration
The server runs in a lightweight Python 3.11 container with:
Non-root user for security
Health checks for monitoring
Volume mounts for data persistence
Network isolation
Security Considerations š
This is a mock implementation for demonstration purposes. In production:
Payment Processing: Integrate with real payment gateways (Stripe, PayPal)
Authentication: Add user authentication and authorization
Data Validation: Implement comprehensive input validation
Rate Limiting: Add API rate limiting
Encryption: Use HTTPS and encrypt sensitive data
Database: Replace JSON files with a real database
Logging: Implement structured logging and monitoring
Future Enhancements š®
Real AMC API Integration: Connect to actual AMC Theatres API
User Accounts: Persistent user profiles and booking history
Group Bookings: Support for multiple users booking together
Loyalty Programs: AMC Stubs integration
Mobile Tickets: Generate QR codes for mobile entry
Seat Recommendations: AI-powered optimal seat suggestions
Price Alerts: Notify users of discounts and promotions
Social Features: Share movie plans with friends
Accessibility: ADA-compliant seat selection
Multi-language: International language support
Contributing š¤
Fork the repository
Create a feature branch:
git checkout -b feature/new-featureMake your changes and add tests
Commit your changes:
git commit -am 'Add new feature'Push to the branch:
git push origin feature/new-featureSubmit a pull request
License š
This project is licensed under the MIT License - see the LICENSE file for details.
Support š¬
For questions, issues, or feature requests:
Create an issue in the GitHub repository
Check the documentation for common solutions
Review the example conversation flows
Happy movie booking! šæš¬
Available Tools
6 toolsbook_seatsC
Reserves selected seats for the user.
Args: showtime_id: Showtime ID (e.g., "st001") seats: List of seat numbers (e.g., ["A5", "A6"]) user_id: User identifier
Returns: JSON string with booking confirmation
Inputs: showtime_id (required), seats (required), user_id (required). Returns: result
get_now_showingB
Returns a list of movies currently showing in a given city or ZIP code.
Args: location: City, state or ZIP code (e.g., "Boston, MA")
Returns: JSON string with list of movies
Inputs: location (required). Returns: result
get_recommendationsB
Suggests movies based on mood, genre, or time preferences.
Args: genre: Movie genre (optional, e.g., "action", "comedy") mood: Mood description (optional, e.g., "exciting", "romantic") time_preference: Time of day preference (optional, e.g., "evening")
Returns: JSON string with movie recommendations
Inputs: genre, mood, time_preference. Returns: result
get_seat_mapA
Displays available and reserved seats for a specific showtime.
Args: showtime_id: Showtime ID (e.g., "st001")
Returns: JSON string with seat availability map
Inputs: showtime_id (required). Returns: result
get_showtimesA
Fetches available showtimes for a specific movie and location.
Args: movie_id: Movie ID (e.g., "mv001") date: Date in YYYY-MM-DD format (e.g., "2025-10-28") location: City, state or ZIP code
Returns: JSON string with available showtimes
Inputs: movie_id (required), date (required), location (required). Returns: result
process_paymentB
Handles simulated payment transaction.
Args: booking_id: Booking ID from book_seats payment_method: Payment method (e.g., "card", "cash") amount: Payment amount in USD
Returns: JSON string with payment confirmation and receipt
Inputs: booking_id (required), payment_method (required), amount (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose within the movie theater booking domain. book_seats handles seat reservations, get_now_showing lists current movies, get_recommendations suggests films, get_seat_map shows seat availability, get_showtimes fetches screening times, and process_payment handles transactions. There is no overlap or ambiguity between these functions.
All six tools follow a consistent verb_noun naming pattern with snake_case. The verbs are appropriate and descriptive: 'book', 'get' (used four times consistently), and 'process'. This uniformity makes the tool set predictable and easy to understand.
With 6 tools, this server is well-scoped for its movie theater booking purpose. It covers the essential workflow from discovery (get_now_showing, get_recommendations) to booking (get_showtimes, get_seat_map, book_seats) to payment (process_payment). Each tool earns its place without being excessive or insufficient.
The tool set covers the core movie booking workflow comprehensively, from discovery to payment. However, there are minor gaps: no tools for canceling bookings, updating reservations, or managing user profiles. These are not critical failures but represent areas where agents might need workarounds.
Maintenance
Related MCP Connectors
Booking gateway for AI agents ā discover events, movies & hotels, hand off to partner checkout.
AI ticket commerce for theme parks, zoos, museums, and aquariums via any AI agent
Discover and book businesses via AI agents.
Live ticket prices, listings and seat maps for AI agents.
Related MCP Servers
- 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.-
- AlicenseAqualityDmaintenanceEnables conversational AI assistants to help users discover movies, find showtimes, book seats, and process payments for AMC Theatres through a simple API interface.6MIT
- 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