Amadeus Flight Availabilities MCP 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

Related MCP server: Amadeus Agent

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

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?

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

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