Click on "Install 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 Show me showtimes for Dune: Part Two in Boston"
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.
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.
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
Python 3.8+
Docker (optional, for containerized deployment)
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_serverBuild and run with Docker Compose:
docker-compose up --buildOr build and run manually:
docker build -t amc-mcp .
docker run -it amc-mcpReturns 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..."
}
]
}Suggests movies based on mood, genre, or preferences.
Input:
{
"genre": "action",
"mood": "exciting"
}Output:
{
"criteria": {"genre": "action", "mood": "exciting"},
"recommendations": [...]
}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
}
]
}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
}
]
}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
}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
}
}Here's how a typical movie booking conversation would work:
User: "Find an action movie near me tonight."
Server calls: get_now_showing + get_recommendations
Returns: 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_seats
Returns: Seat selection and booking confirmation
User: "Pay with my card."
Server calls: process_payment
Returns: Payment confirmation with digital receipt
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 file{
"movie_id": str,
"title": str,
"rating": str, # PG, PG-13, R, etc.
"duration": int, # Minutes
"genre": str,
"description": str,
"poster_url": str
}{
"theater_id": str,
"name": str,
"address": str,
"city": str,
"state": str,
"zip_code": str
}{
"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
}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"
}Edit data/theaters.json:
{
"theater_id": "th011",
"name": "AMC New Location 15",
"address": "123 Main Street",
"city": "New City",
"state": "NY",
"zip_code": "12345"
}Edit data/showtimes.json and data/seats.json to add new showtimes and corresponding seat maps.
You can test individual tools using the MCP inspector or by connecting to any MCP-compatible client.
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"
PYTHONPATH: Set to /app/src for proper module resolution
PYTHONUNBUFFERED: Set to 1 for real-time logging
MCP_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
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
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
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
Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Make your changes and add tests
Commit your changes: git commit -am 'Add new feature'
Push to the branch: git push origin feature/new-feature
Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
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! šæš¬
Reserves selected seats for the user.
| Name | Required | Description | Default |
|---|---|---|---|
| seats | Yes | List of seat numbers (e.g., ["A5", "A6"]) | |
| user_id | Yes | User identifier | |
| showtime_id | Yes | Showtime ID (e.g., "st001") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects, but it only says 'Reserves' without detailing behaviors like availability checks, error handling, idempotency, or any impact on payment. This is a significant transparency gap for a mutating action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, front-loaded with the core action. It is appropriately short, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a booking action with three required parameters and an output schema), the description lacks essential context about workflow integration (e.g., payment linkage), success/failure semantics, and expected usage flow. It does not sufficiently support an agent's decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description, so the baseline is 3. The tool description adds no additional meaning beyond what the schema already provides, neither enhancing nor detracting from parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (reserves) and the resource (selected seats), which is specific enough. However, it does not mention the showtime context or differentiate from sibling tools like process_payment, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, prerequisites, or how it fits into a larger workflow. There is no mention of alternatives or exclusions, so an agent has no contextual cues for timing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a list of movies currently showing in a given city or ZIP code.
| Name | Required | Description | Default |
|---|---|---|---|
| location | Yes | City, state or ZIP code (e.g., "Boston, MA") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what it does but does not disclose any limitations (e.g., data freshness, geographic coverage), error conditions, or performance characteristics. For a simple read-only lookup, this may be acceptable, but it adds nothing beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to detail return values. The parameter is fully documented, and the tool's purpose is clear. It lacks only subtle context like timezone handling or data update frequency, but it's adequate for this simple listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'location' already has a clear description with an example. The tool description does not add additional semantics beyond what the schema provides. Baseline 3 applies because the schema covers everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a list of currently showing movies for a given city or ZIP. The verb 'returns' and resource 'movies currently showing' are specific, and the scope differentiates it from siblings like get_showtimes (which focuses on showtimes) and get_recommendations (recommendations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates this is for listing movies in a location, contrasting with siblings like get_showtimes or get_seat_map. However, it lacks explicit 'when to use' vs 'when not to use' guidance. The context is clear enough for an agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggests movies based on mood, genre, or time preferences.
| Name | Required | Description | Default |
|---|---|---|---|
| mood | No | Mood description (optional, e.g., "exciting", "romantic") | |
| genre | No | Movie genre (optional, e.g., "action", "comedy") | |
| time_preference | No | Time of day preference (optional, e.g., "evening") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool 'suggests movies,' implying a read-only operation, but it does not elaborate on behavior such as handling of no parameters, output format, or any limitations. The description is minimal and does not add rich context beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, complete sentence that is front-loaded and directly conveys the core function. There is no redundant or filler content, earning every word. It is appropriately concise for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three optional parameters and an output schema, so the description does not need to specify return values. The description adequately covers the tool's primary purpose and inputs, and the output schema likely details the response structure. However, it leaves some behavioral nuances (e.g., what happens if all params are null) implied, though this is minor given the simplicity of the tool and presence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions and examples for each parameter (mood, genre, time_preference). The tool description merely echoes these parameter names without adding new meaning. Since schema coverage is high, the baseline of 3 is appropriate; the description does not enhance the understanding beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Suggests movies based on mood, genre, or time preferences.' It uses a specific verb ('suggests') and resource ('movies'), and the mention of mood, genre, and time preferences distinguishes it from sibling tools like get_now_showing and get_showtimes which focus on current listings or specific showtimes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when the user has mood, genre, or time preferences for movie recommendations. It does not explicitly mention alternatives or exclusions, but the sibling tool names (get_showtimes, get_seat_map, book_seats, process_payment, get_now_showing) imply distinct use cases, and the description's focus on recommendations is sufficient to guide basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Displays available and reserved seats for a specific showtime.
| Name | Required | Description | Default |
|---|---|---|---|
| showtime_id | Yes | Showtime ID (e.g., "st001") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and 'Displays' suggests a read-only operation, which is helpful. However, it does not explicitly state safety guarantees, authentication needs, or failure behavior, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly written sentence with a clear verb and object. It avoids filler and places the key scope ('specific showtime') up front.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool with an output schema, the description is mostly complete: it states the input, resource, and displayed data. It loses a point because it does not guide usage relative to sibling tools, though the output schema covers return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents showtime_id with an example ('st001'), and the description adds no meaning beyond referencing 'a specific showtime.' Since schema coverage is 100%, the baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Displays') and resource ('available and reserved seats for a specific showtime'), making the tool's function unmistakable. It also distinguishes itself from siblings like get_showtimes (which lists showtimes) and book_seats (which modifies seat availability).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing seat availability for a chosen showtime, but it does not explicitly state when to use it versus alternatives or when not to use it. It provides enough context for basic selection but lacks explicit usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches available showtimes for a specific movie and location.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date in YYYY-MM-DD format (e.g., "2025-10-28") | |
| location | Yes | City, state or ZIP code | |
| movie_id | Yes | Movie ID (e.g., "mv001") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It indicates a read-only fetch, but it does not disclose data scope, matching behavior, failure modes, or output conventions. This is minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the verb and object. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, complete parameter schema, and presence of an output schema, the description covers the essential operation sufficiently. It could be improved with sibling differentiation, but it is not incomplete for this simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (movie_id, date, location), so the schema already does the heavy lifting. The description adds no additional parameter-level meaning beyond what is already structured.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetches') and identifies the resource ('available showtimes') and scope ('for a specific movie and location'). It distinguishes the tool from siblings like get_seat_map and book_seats, though it omits the date dimension that is a required parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as get_now_showing or get_recommendations. Usage context is only implied by the verb and resource, with no exclusions or alternative conditions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Handles simulated payment transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Payment amount in USD | |
| booking_id | Yes | Booking ID from book_seats | |
| payment_method | Yes | Payment method (e.g., "card", "cash") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It says 'simulated' which hints at non-real payment, but it does not disclose what happens on success/failure, whether it mutates state (e.g., marks booking as paid), or any side effects. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It is not verbose, but it is under-specified rather than concise in a helpful way. Still, it earns a 4 for brevity and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and three required parameters, the description is too thin. It does not explain the payment flow, what the output represents, or any error conditions. The 'simulated' aspect is mentioned but not elaborated. The description is not complete enough for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no extra meaning beyond 'simulated payment transaction,' which does not clarify parameter relationships or constraints. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Handles simulated payment transaction,' which identifies the action (process payment) and resource (transaction), but it is vague about the specific scope (e.g., what happens after payment, whether it confirms booking). It does not distinguish from siblings, though siblings are mostly read-oriented, so the purpose is somewhat clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention that it should be used after book_seats, nor any prerequisites or sequencing. The description implies usage for payment but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0book_seatsget_now_showingget_recommendationsget_seat_mapget_showtimesprocess_paymentScored across 6 tools
Each tool targets a distinct step in the movie-booking flow: recommendations, showtimes, seat maps, booking, payment, and now-showing lists. The only slight overlap is between get_recommendations and get_now_showing, but their purposes (personalized suggestions vs. current listings) are clear enough.
All tools use a consistent verb_noun pattern (get_, book_, process_), which is predictable. Minor deviation: 'process_payment' uses a generic verb compared to the more specific 'get_' and 'book_' verbs, but it still fits the pattern.
Six tools is well-scoped for a movie booking domain, covering the essential user journey from discovery to payment without unnecessary bloat. Each tool serves a clear purpose in the workflow.
The surface covers the core booking lifecycle: discover movies, check showtimes, view seats, book, and pay. A minor gap is the lack of a cancellation or refund tool, but the simulated payment and booking flow is otherwise complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
An AI concierge that turns static forms into adaptive AI conversations. From any MCP client.
