FareOS MCP Server

A Model Context Protocol (MCP) server for real-time flight booking using the FareOS (SeatEleven) API.

Features

This MCP server provides 7 powerful tools for flight booking:

1. search_airports

Search for airports by name, city, or IATA code to get airport details.

2. search_flights

Search for available flights with comprehensive filtering options:

• One-way, round-trip, and multi-city searches
• Multiple passenger types (adults, children, infants)
• Cabin class selection (economy, business, first)
• Fare type filtering (refundable/non-refundable)

3. get_fare_rules

Get detailed fare rules, cancellation policies, and penalties for specific flights.

4. review_pricing

Validate flight availability and pricing before booking to ensure accurate rates.

5. authenticate_user

Initiate OTP-based authentication for secure booking (sends OTP to email).

6. verify_otp

Verify OTP code and obtain authentication token for booking.

7. book_flight

Complete flight booking with passenger details and payment processing.

Installation

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

1. Copy the environment template:

cp .env.example .env

2. Edit .env and set your FareOS credentials:

FAREOS_API_BASE_URL=https://api.b2bmeta.com
FAREOS_CLIENT_ID=your_client_id_here

Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fareos": {
      "command": "npx",
      "args": ["-y", "fareos-mcp"],
      "env": {
        "FAREOS_API_BASE_URL": "https://api.b2bmeta.com",
        "FAREOS_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

Example Workflow

1. Search for Airports

User: "Find airports in Hyderabad"
AI uses: search_airports(query="Hyderabad")

2. Search for Flights

User: "Search for flights from HYD to MAA on 2025-12-10 for 2 adults"
AI uses: search_flights({
  from: "HYD",
  to: "MAA",
  departDate: "2025-12-10",
  adults: 2
})

3. Get Fare Rules

User: "What are the cancellation rules for this flight?"
AI uses: get_fare_rules({
  tui: "abc123",
  provider: "TripJack",
  fareId: "xyz789"
})

4. Review Pricing

User: "Confirm the price for these flights"
AI uses: review_pricing({
  provider: "TripJack",
  trips: [{
    TUI: "abc123",
    priceIds: ["xyz789"]
  }]
})

5. Authenticate

User: "I want to book this flight, my email is [email protected]"
AI uses: authenticate_user({email: "[email protected]"})

6. Verify OTP

User: "My OTP is 123456"
AI uses: verify_otp({
  email: "[email protected]",
  otp: "123456"
})

7. Book Flight

User: "Book this flight for John Doe, DOB 1990-01-15"
AI uses: book_flight({
  tui: "abc123",
  provider: "TripJack",
  priceIds: ["xyz789"],
  passengers: [{
    title: "Mr",
    firstName: "John",
    lastName: "Doe",
    dateOfBirth: "1990-01-15"
  }],
  contactEmail: "[email protected]",
  contactPhone: "+1234567890"
})

API Endpoints Used

Based on the Postman collection, this server integrates with:

• Airport Search: GET /config/airports/search
• Flight Search: POST /aggr/search
• Fare Rules: POST /aggr/v1/farerule
• Price Review: POST /aggr/v1/review
• Auth OTP: POST /auth/auth/customer/initiate/otp
• OTP Verify: POST /auth/auth/customer/verify-otp
• Book Flight: POST /booking/api/v1/flight-booking/cashfree/flight/book

Development

# Watch mode for development
npm run watch

# Build for production
npm run build

# Start the server
npm start

Architecture

The server is built using:

• @modelcontextprotocol/sdk: MCP protocol implementation
• axios: HTTP client for API requests
• TypeScript: Type-safe development

The FareOSAPI class handles all API interactions with automatic authentication token management through axios interceptors.

Security Notes

• Authentication tokens are managed in-memory and not persisted
• OTP-based authentication provides secure booking flow
• All API requests use HTTPS
• Sensitive data (passwords, payment details) are never stored

Troubleshooting

"Authentication required" error

Make sure to call authenticate_user and verify_otp before attempting to book flights.

"Invalid API response" error

Check that your FAREOS_CLIENT_ID is correctly set in the environment variables.

Connection refused

Verify that the FAREOS_API_BASE_URL is accessible and correct.

License

MIT

Support

For issues related to:

• MCP Server: Open an issue in this repository
• FareOS API: Contact FareOS support at [support email]