Amadeus Flight Availabilities App

An MCP (Model Context Protocol) App with interactive dashboard UI that integrates with the Amadeus Flight Availabilities Search API. This application allows users to search for available flights and view seat availability in real-time.

Current Status

Component	Status
Project Setup	✅ Complete
MCP Server	✅ Complete
React Dashboard	✅ Complete
shadcn/ui Components	✅ Complete
Single-file Build	✅ Complete
Server-side API Proxy	✅ Complete (Security fix)
Standalone Mode	✅ Complete
Claude Code CLI Support	✅ Complete
Claude Desktop Support	✅ Complete

What It Does

The Amadeus Flight Availabilities Search API answers the question: "How many seats are still available on this flight?"

This MCP App provides:

• Interactive flight search form with IATA airport codes
• Real-time seat availability display per booking class
• Filter options by cabin class, airline, and number of stops
• Visual availability indicators (available, limited, full/waitlist)

Features

• Flight Search: Search by origin/destination IATA codes and date
• Seat Availability: View available seats per booking class (Economy, Business, First)
• Flight Details: Carrier info, aircraft type, departure/arrival times, terminals
• Filtering: Filter by cabin class, airlines, and connection preferences
• Interactive Dashboard: Rich UI with expandable flight details

Tech Stack

Category	Technology
Framework	React 18 + TypeScript
UI Library	shadcn/ui + Tailwind CSS
MCP SDK	@modelcontextprotocol/sdk + @modelcontextprotocol/ext-apps
Bundler	Vite + vite-plugin-singlefile
Validation	Zod
Server	Express (HTTP transport)
Package Manager	bun

Prerequisites

• Node.js 18+
• bun runtime
• Amadeus API credentials (Client ID and Client Secret)
• Claude Code CLI (recommended) OR Claude Desktop

Quick Start

1. Clone and Install

# Navigate to project directory
cd amadeus-flights-mcp-app

# Install dependencies
bun install

2. Configure Environment

Copy .env.example to .env and add your Amadeus credentials:

cp .env.example .env

Edit .env:

AMADEUS_CLIENT_ID=your_api_key
AMADEUS_CLIENT_SECRET=your_api_secret

3. Build the Project

bun run build

4. Start the Server

bun run dev

The server will be available at http://localhost:3001.

Claude Integration

Option 1: Claude Code CLI (Recommended)

Claude Code CLI supports HTTP transport, which provides the best experience for interactive MCP Apps with UI.

# Add MCP server to Claude Code
claude mcp add amadeus-flights http://localhost:3001/mcp

Then ask Claude:

"Search for flights from JFK to LHR on March 15, 2025"

Option 2: Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "amadeus-flights": {
      "command": "bun",
      "args": ["PATH/TO/amadeus-flights-mcp-app/main.ts", "--stdio"],
      "env": {
        "AMADEUS_CLIENT_ID": "your_client_id",
        "AMADEUS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Option 3: Standalone Mode (No Claude)

Simply open http://localhost:3001 in your browser. The React dashboard works without Claude.

Usage

Standalone Mode (Browser)

1. Start the server: bun run dev
2. Open browser: Go to http://localhost:3001
3. Use the dashboard: Search for flights using the form
4. API status: Check if Amadeus API is configured via the status indicator

Claude Mode

1. Start the server: bun run dev (for Claude Code) or bun run serve (for Claude Desktop)
2. Open Claude (Code CLI or Desktop)
3. Ask Claude: "Search for flights from JFK to LHR on 2024-12-15"
4. View results: Interactive dashboard shows available flights with seat counts
5. Filter: Use filters to narrow down by cabin class, carrier, or stops

Which Claude to Use?

Feature	Claude Code CLI	Claude Desktop
HTTP Transport	✅ Yes	❌ No (stdio only)
Interactive UI	✅ Renders properly	⚠️ May not render
Setup Complexity	Lower	Higher (path required)

Recommendation: Use Claude Code CLI for the best experience with interactive MCP Apps.

Security

Important: Amadeus API credentials are never exposed to the browser.

• Credentials are stored server-side in environment variables
• Frontend calls the /api/flights proxy endpoint
• The server handles OAuth2 authentication internally
• Built bundle contains no credentials (verified with grep)

Security Features

Feature	Description
CORS	Restricted to localhost origins (configurable via ALLOWED_ORIGINS)
Security Headers	X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
Request Limit	10KB max for API request body
Credentials	Never embedded in browser bundle

API Reference

• Amadeus API: Flight Availabilities Search
• Authentication: OAuth 2.0 with client credentials
• Test Environment: https://test.api.amadeus.com/v1

Project Structure

amadeus-flights-mcp-app/
├── src/
│   ├── components/           # React components
│   │   ├── ui/              # shadcn/ui components
│   │   └── Flight*.tsx      # Flight search & results
│   ├── lib/                 # Utilities
│   │   ├── amadeus.ts       # API client (server-side)
│   │   └── utils.ts         # Helper functions
│   ├── types/               # TypeScript types
│   └── styles/              # CSS
├── server.ts                # MCP server
├── main.ts                  # Entry point (Express server + API proxy)
├── dist/                    # Built frontend
├── docs/                    # Documentation
└── .env                     # Environment variables (not committed)

Documentation

• Getting Started - Detailed setup guide
• Claude Setup - Connect to Claude Code CLI or Claude Desktop
• API Reference - Amadeus API documentation
• Architecture - System design
• User Guide - Usage instructions

Changelog

See CHANGELOG.md for version history.

License

MIT

Resources

• MCP Apps Documentation
• Amadeus Developers Portal
• shadcn/ui