# @striderlabs/mcp-southwest

MCP server for Southwest Airlines — search flights, manage bookings, check in, and manage your Rapid Rewards account via browser automation.

## Features

- **Search flights** with real-time pricing across all fare classes
- **Compare fares**: Wanna Get Away, Wanna Get Away+, Anytime, Business Select
- **Book flights** with dollars or Rapid Rewards points
- **Manage reservations**: change, cancel, get details
- **No change fees** — Southwest never charges them
- **Check in** online (opens exactly 24 hours before departure)
- **Get boarding passes** with group/position (A/B/C)
- **Early Bird Check-In** — auto check-in 36 hours before departure
- **Rapid Rewards** — check points balance, tier status, Companion Pass progress

## Prerequisites

- Node.js 18+
- [Playwright browsers](https://playwright.dev/): `npx playwright install chromium`

## Installation

```bash
npm install -g @striderlabs/mcp-southwest
# or
npx @striderlabs/mcp-southwest
```

## Setup

### Environment Variables

Create a `.env` file or set these in your environment:

```env
# Required for account-based tools (check-in, Rapid Rewards, points booking)
SW_USERNAME=your_rapid_rewards_number_or_email
SW_PASSWORD=your_password

# Optional
SW_HEADLESS=true   # Set to "false" to see the browser (useful for debugging)
```

### Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "southwest": {
      "command": "npx",
      "args": ["@striderlabs/mcp-southwest"],
      "env": {
        "SW_USERNAME": "your_rapid_rewards_number",
        "SW_PASSWORD": "your_password"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "southwest": {
      "command": "mcp-southwest",
      "env": {
        "SW_USERNAME": "your_rapid_rewards_number",
        "SW_PASSWORD": "your_password"
      }
    }
  }
}
```

## Available Tools

### `search_flights`
Search for available Southwest flights.

```json
{
  "originAirport": "DAL",
  "destinationAirport": "LAX",
  "departureDate": "2024-06-15",
  "passengers": 2,
  "tripType": "oneway",
  "fareType": "USD"
}
```

### `get_flight_details`
Get status and details for a specific flight.

```json
{
  "flightNumber": "WN1234",
  "flightDate": "2024-06-15",
  "originAirport": "DAL",
  "destinationAirport": "LAX"
}
```

### `select_flight`
Select a flight from search results to proceed with booking.

```json
{
  "flightIndex": 0,
  "fareType": "wanna-get-away"
}
```

### `get_fares`
Compare fare classes with pricing and benefits.

```json
{
  "originAirport": "HOU",
  "destinationAirport": "MCO",
  "departureDate": "2024-07-04",
  "fareType": "USD"
}
```

### `add_early_bird`
Add Early Bird Check-In to an existing booking (~$15–25/person/flight).

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith"
}
```

### `checkout`
Complete a booking with passenger and payment details.

```json
{
  "firstName": "Jane",
  "lastName": "Smith",
  "dateOfBirth": "01/15/1990",
  "gender": "F",
  "email": "jane@example.com",
  "phone": "5551234567",
  "cardNumber": "4111111111111111",
  "cardExpiration": "12/26",
  "cardCvv": "123",
  "cardZip": "75201",
  "cardName": "Jane Smith",
  "addEarlyBird": false
}
```

### `get_reservation`
Look up a booking by confirmation number.

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith"
}
```

### `change_flight`
Modify an existing booking (no change fees!).

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith",
  "newDepartureDate": "2024-06-20"
}
```

### `cancel_flight`
Cancel a reservation. Use `confirm: true` to actually cancel.

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith",
  "confirm": true
}
```

### `check_in`
Check in online (available 24 hours before departure).

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith"
}
```

### `get_boarding_pass`
Retrieve boarding pass with group and position number.

```json
{
  "confirmationNumber": "ABC123",
  "firstName": "Jane",
  "lastName": "Smith",
  "savePath": "~/boarding-pass.pdf"
}
```

### `get_rapid_rewards`
Check Rapid Rewards points, tier status, and Companion Pass progress.

```json
{}
```
*(Uses `SW_USERNAME`/`SW_PASSWORD` env vars)*

### `book_with_points`
Search for flights and book using Rapid Rewards points.

```json
{
  "originAirport": "DAL",
  "destinationAirport": "DEN",
  "departureDate": "2024-08-10",
  "passengers": 1
}
```

## Southwest Airlines Fare Classes

| Fare | Refundable | Points Multiplier | Boarding |
|------|-----------|-------------------|---------|
| Wanna Get Away | Travel funds | 6x base | Standard |
| Wanna Get Away+ | Transferable funds | 8x base | Standard |
| Anytime | Full refund | 10x base | Priority (A1–A15) |
| Business Select | Full refund | 12x base | Guaranteed A1–A15 |

## Southwest Boarding System

Southwest uses **open seating** — no assigned seats. Passengers board in groups:
- **Group A** (A1–A60): Early Bird / Business Select / Anytime priority
- **Group B** (B1–B60): General boarding
- **Group C** (C1–C60): Last to board

Check-in order determines boarding position. Check in exactly at the 24-hour mark for the best position.

## Session Persistence

Login sessions are saved to `~/.config/mcp-southwest/session.json` to avoid re-authenticating on every run.

## Development

```bash
git clone https://github.com/markswendsen-code/mcp-southwest
cd mcp-southwest
npm install
npx playwright install chromium
npm run build
npm start
```

For development with hot reload:
```bash
npm run dev
```

To see the browser during automation (useful for debugging):
```bash
SW_HEADLESS=false npm run dev
```

## License

MIT © Strider Labs