# 🎬 Movie Booking MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets Claude Desktop search for movies, check your Google Calendar, and book tickets — all through natural conversation.

---

## ✨ Features

- **Search movies** via IMDb (RapidAPI) with real ratings, genres, and show times
- **Check calendar conflicts** via Google Calendar before booking
- **Book tickets** with a confirmed booking ID, seat type, and INR pricing
- **Demo mode** — works out of the box without any API keys

---

## 🗂️ Project Structure

```
C:\AI_CODES\MCP\
├── server.py          ← MCP server (3 tools)
├── .env               ← API keys (never commit this)
├── requirements.txt   ← Python dependencies
└── venv\              ← Virtual environment
```

---

## ⚡ Quick Start

### 1. Clone & set up environment

```bash
cd C:\AI_CODES\MCP
python -m venv venv
venv\Scripts\activate
pip install mcp fastmcp requests python-dotenv
```

### 2. Create `.env`

```env
RAPIDAPI_KEY=your_rapidapi_key_here
GOOGLE_CALENDAR_ID=primary
```

> **No API key?** Leave `RAPIDAPI_KEY` blank — the server automatically uses built-in demo data.

### 3. Configure Claude Desktop

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "movie-booking": {
      "command": "C:\\AI_CODES\\MCP\\venv\\Scripts\\python.exe",
      "args": ["-u", "C:\\AI_CODES\\MCP\\server.py"]
    }
  }
}
```

### 4. Restart Claude Desktop

The server should appear with a green **running** badge under **Settings → Developer → Local MCP Servers**.

---

## 🛠️ Tools

| Tool | Description |
|------|-------------|
| `search_movies` | Search IMDb for movies by name and city |
| `check_calendar` | Check Google Calendar for conflicts on a date/time |
| `book_movie_ticket` | Confirm a booking and get a unique booking ID |

### Seat Types & Pricing

| Type | Price (INR) |
|------|-------------|
| `standard` | ₹ 200 |
| `premium` | ₹ 350 |
| `recliner` | ₹ 500 |

---

## 💬 Example Prompts

```
Is "Inception" playing in Mumbai?
```

```
Am I free on June 20, 2025 at 8 PM for a movie?
```

```
Search for "Interstellar" in Hyderabad, check if I'm free on
June 25 at 8 PM, and book 2 premium tickets if the slot is clear.
```

---

## 🔧 How `@mcp.tool()` Works

Each tool is a plain Python function decorated with `@mcp.tool()`. FastMCP automatically:

- Generates a JSON schema from the **type hints**
- Uses the **docstring** as the tool description Claude reads
- Handles **serialisation** of the returned dict to JSON

```python
@mcp.tool()
def search_movies(movie_name: str, city: str = "Mumbai") -> dict:
    """
    Search for movies currently in theaters using the IMDb API.

    Args:
        movie_name: The name of the movie to search for.
        city: City to find local show times (default: Mumbai).
    """
    # ...
```

The server runs over **stdio** — no HTTP server or open port needed.

---

## 🔑 Getting a RapidAPI Key

1. Sign up at [rapidapi.com](https://rapidapi.com)
2. Subscribe to **IMDb8 API** (free tier)
3. Subscribe to **Google Calendar API**
4. Copy your key and paste it into `.env`

---

## 🐛 Troubleshooting

| Symptom | Fix |
|---------|-----|
| Server not appearing in Claude | Fully quit & restart Claude Desktop; check JSON config syntax |
| `ModuleNotFoundError: fastmcp` | Activate venv, run `pip install fastmcp` |
| `Demo data (RAPIDAPI_KEY not set)` | Expected — set key in `.env` for live data |
| HTTP 401 / 403 | Invalid `RAPIDAPI_KEY` |
| HTTP 429 | Rate limit hit — wait 1 minute |
| "You've hit your message limit" | Claude Desktop usage cap — not a server issue; wait for reset |

---

## 📄 License

MIT