Flight Search MCP

Full-stack flight search application demonstrating the Model Context Protocol (MCP) with real-time Google Flights data.

Overview

This is a monorepo featuring a Next.js frontend and Spring Boot MCP server that provides live flight search capabilities using SerpAPI's Google Flights API.

Tech Stack:

• Frontend: Next.js 16 + React 19 + TypeScript + Tailwind CSS
• Backend: Spring Boot 3.4.5 + Spring AI 1.1.0 + Java 17
  • MCP Flight Server (port 8080) - Flight search tools
  • MCP Client Service (port 8081) - AI chat integration
• Protocol: Model Context Protocol (MCP) over HTTP Streaming
• AI: Anthropic Claude Sonnet 4.5
• API: SerpAPI Google Flights

Quick Start

Prerequisites

• Frontend: Node.js 18+ and npm
• Backend: Java 17+ and Maven 3.6+
• API Keys:
  • SerpAPI key (get one at serpapi.com)
  • Anthropic API key (get one at console.anthropic.com)

Setup

1. Clone the repository:

   git clone https://github.com/apappascs/mcp-flight-search.git
   cd flight-search-mcp

2. Set environment variables:

   export SERP_GOOGLE_FLIGHTS_API_KEY=your_serpapi_key_here
   export ANTHROPIC_API_KEY=your_anthropic_key_here

3. Start everything (recommended):

   ./start-all.sh

   This script will:

   • Verify both API keys
   • Start MCP Flight Server on port 8080
   • Start MCP Client Service on port 8081
   • Start frontend on port 3000
   • Open browser automatically
   • Display logs in real-time

Manual Start

Terminal 1 - MCP Flight Server:

cd backend/mcp-flight-server
./mvnw spring-boot:run

Terminal 2 - MCP Client Service:

cd backend/mcp-client-service
./mvnw spring-boot:run

Terminal 3 - Frontend:

cd frontend
npm install  # First time only
npm run dev

Browser:

open http://localhost:3000

Project Structure

flight-search-mcp/
├── frontend/                        # Next.js application (port 3000)
│   ├── app/                        # App router pages
│   ├── components/                 # React components
│   ├── lib/                        # MCP & AI chat clients
│   ├── types/                      # TypeScript types
│   └── README.md                   # Frontend documentation
│
├── backend/
│   ├── mcp-flight-server/          # MCP Flight Server (port 8080)
│   │   ├── src/main/java/          # Flight search service
│   │   ├── src/main/resources/     # Configuration
│   │   └── README.md               # Server documentation
│   │
│   └── mcp-client-service/         # MCP Client Service (port 8081)
│       ├── src/main/java/          # AI chat integration
│       ├── src/main/resources/     # Configuration
│       └── README.md               # Client documentation
│
├── start-all.sh                    # One-command launcher
├── logs/                           # Application logs
├── README.md                       # This file
└── CLAUDE.md                       # Claude Code guide

Features

• Dual Search Modes: Classic form-based search + AI chat powered by Claude
• MCP Flight Server: Provides flight search tools via Model Context Protocol
• AI Integration: Natural language flight queries using Claude Sonnet 4.5
• Real-time Data: Live flight information from Google Flights via SerpAPI
• Lufthansa Focus: Optimized for Lufthansa Group airlines

Development

Frontend Scripts

cd frontend

npm run dev      # Start development server
npm run build    # Build for production
npm run lint     # Run linter
npm run clean    # Clean build artifacts
npm run rebuild  # Full rebuild

Backend Scripts

cd backend/mcp-flight-server

./mvnw clean package        # Build
./mvnw spring-boot:run      # Run server
./start-server.sh           # Run with startup script

Testing

Health Checks

# Backend health
curl http://localhost:8080/actuator/health

# Frontend API health
curl http://localhost:3000/api/flights/search

Example Search

Search Frankfurt (FRA) to Berlin (BER):

curl -X POST http://localhost:3000/api/flights/search \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "Frankfurt/Main International",
    "destination": "Berlin - Brandenburg",
    "departureDate": "2025-12-01",
    "returnDate": "2025-12-08",
    "tripType": "roundTrip",
    "travelClass": "Economy",
    "travelers": 1
  }'

Architecture

Classic Search Flow

User Browser (localhost:3000)
    ↓ HTTP POST
Next.js API Route
    ↓ MCP over HTTP Streaming
MCP Flight Server (localhost:8080)
    ↓ REST API
SerpAPI (Google Flights)

AI Chat Search Flow

User Browser (localhost:3000)
    ↓ HTTP POST
Next.js API Route
    ↓ HTTP
MCP Client Service (localhost:8081)
    ↓ Anthropic API
Claude Sonnet 4.5
    ↓ MCP Tool Calls
MCP Flight Server (localhost:8080)
    ↓ REST API
SerpAPI (Google Flights)

Configuration

Frontend

No configuration required. Default MCP server: http://localhost:8080/mcp

Backend

Edit backend/mcp-flight-server/src/main/resources/application.properties:

server.port=8080
spring.ai.mcp.server.path=/mcp
serpapi.api.key=${SERP_GOOGLE_FLIGHTS_API_KEY}
serpapi.localization.country=de
serpapi.localization.language=en
serpapi.localization.currency=EUR

Troubleshooting

API Key Issues

# Verify keys are set
echo $SERP_GOOGLE_FLIGHTS_API_KEY
echo $ANTHROPIC_API_KEY

# Set if missing
export SERP_GOOGLE_FLIGHTS_API_KEY=your_serpapi_key
export ANTHROPIC_API_KEY=your_anthropic_key

Port Conflicts

# Check if ports are in use
lsof -i :3000  # Frontend
lsof -i :8080  # MCP Flight Server
lsof -i :8081  # MCP Client Service

# Kill processes if needed
kill -9 <PID>

Build Issues

# Frontend
cd frontend
npm run clean
npm install
npm run build

# Backend
cd backend/mcp-flight-server
./mvnw clean package

Connection Issues

Ensure backend is running before starting frontend:

curl http://localhost:8080/actuator/health

Documentation

• Frontend README - Frontend setup and development
• MCP Flight Server README - Flight search MCP tools
• MCP Client Service README - AI chat integration

This is a demonstration project showcasing MCP integration patterns. Feel free to use it as a reference for building your own MCP applications.