AMC MCP Server

How to use

Start by launching the MCP server locally or in a container, then connect to it using an MCP client. You can perform a full booking flow that includes discovering current showings, getting showtimes for a chosen movie and location, inspecting seat availability, reserving seats, and completing a mock payment. Use conversational prompts to guide the user through selecting a movie, choosing a theater, picking seats, and confirming the reservation and receipt.

How to install

Prerequisites you need before starting are Python 3.8 or newer.

Option 1. Local installation

1. Install Python and ensure it is accessible in your PATH.

2. Install the package dependencies.

3. Run the MCP server locally.

4. Use the server with an MCP client to start interacting with movie data and bookings.

Option 2. Docker deployment

1. Deploy with Docker Compose to bring up the service and data layers.

2. Alternatively build and run the container manually if you prefer.

Additional setup and configuration

Configuration highlights you may encounter include environment variables to adjust logging and runtime behavior, and Docker-based deployment options with health checks and volume mounts for data persistence.

Configuration and security

Environment variables you may set include log level and Python behavior controls. For production use, plan real payment integration, authentication, input validation, rate limiting, and encrypted transport. In this mock setup, payments are simulated and data is stored in JSON files for demonstration.

Notes and troubleshooting

Common issues typically relate to Python version compatibility, missing dependencies, or container startup problems. Verify the Python path, ensure required dependencies are installed, and check startup logs for errors. If you encounter issues starting the server in Docker, ensure Docker and Docker Compose are installed and that the data volumes are accessible.

Data sources and endpoints overview

The server provides endpoints to list current movies, fetch showtimes by movie and location, display seat maps for a showtime, reserve seats, and process mock payments. All actions are designed to drive an end-to-end booking flow within a unified MCP server.

Code and runtime configuration

You can start the server with the following runtime command when running locally: python -m amc_mcp.fastmcp_server.

Usage example flow

1) Discover action movies near a location and request recommendations. 2) Pick a movie and fetch its showtimes for today. 3) Choose a showtime and view the seat map. 4) Reserve seats and receive a booking confirmation. 5) Complete a mock payment and obtain a receipt.

Development and testing notes

Manual testing can be performed by connecting an MCP client to the server and stepping through the flow from discovery to payment. For testing with compatible clients, verify that each tool endpoint responds as expected and that the booking lifecycle updates accordingly.

Environment and tooling

Primary language: Python. Package management uses Python tools like pip to install dependencies. You may also use Docker and Docker Compose for containerized deployment.

External endpoints and containerization

If you choose containerized deployment, you can run with Docker Compose or build the image manually and start the container. The containerization setup includes a non-root runtime user, health checks, and volume mounts for persistent data.

What you get with this MCP server

A complete, mock-enabled MCP server that handles movie discovery, showtimes, seating, bookings, and payments, with multi-location support and a straightforward API surface designed for conversational assistants.

Appendix: Quick reference commands

{
  "mcpServers": {
    "amc_mcp": {
      "command": "python",
      "args": ["-m", "amc_mcp.fastmcp_server"]
    }
  }
}

get_now_showing

Returns a list of movies currently showing at a given location.

get_recommendations

Suggests movies based on genre, mood, or user preferences.

get_showtimes

Fetches available showtimes for a specific movie and location.

get_seat_map

Displays available and reserved seats for a showtime.

book_seats

Reserves selected seats for a user and returns a booking summary.

process_payment

Simulates a payment transaction and returns a receipt.