Awardmath

awardmath-mcp connects AI assistants to the public AwardMath API through the Model Context Protocol.

AwardMath is the travel points optimizer. You provide your points balances and a travel goal. A deterministic solver searches a versioned graph of transfer ratios and award charts, then returns up to three verified, explainable booking plans.

The math is enumeration and scoring over published charts. An LLM can parse your question and explain the results, but it never chooses or optimizes the plans.

This repository contains the MCP server and a free data snapshot under data/. The server is read-only. It requires no API key, login, or subscription, and it does not scrape airline sites.

Tools

The server exposes three tools.

Tool	What it does
list_programs	Lists tracked and spendable programs
solve_award_trip	Returns up to three plans
parse_wallet	Structures wallet text

list_programs

list_programs returns every program AwardMath tracks and identifies which program IDs a solve can spend today.

Spendable programs include award programs with priced charts and bank currencies that transfer into one of those programs. This distinction prevents an assistant from asking the solver to spend a balance that has no path to a priced award.

solve_award_trip

solve_award_trip searches for plans that fit your wallet, origins, destinations, cabins, traveler count, and cash cap.

A successful response contains up to three plans with:

• Exact transfer steps
• Total points required
• Priced fees

If no plan fits, the response includes no_plan_reasons. These identify the constraint that failed instead of filling the gap with a guessed route or price.

parse_wallet

parse_wallet turns free text into structured balances.

For example:

250k Amex, 80k Chase

Clear balances become program IDs and amounts. Ambiguous phrases are surfaced for clarification rather than assigned to a program by guesswork.

Setup

You can run the server directly from GitHub or install it from a clone.

Claude Code

claude mcp add awardmath -- uvx --from git+https://github.com/DanCastHub/awardmath-mcp awardmath-mcp

Claude Desktop or another JSON-configured MCP client

{
  "mcpServers": {
    "awardmath": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DanCastHub/awardmath-mcp", "awardmath-mcp"]
    }
  }
}

From a clone

pip install -e .
awardmath-mcp

No API key or AwardMath account is required.

Example

Ask your assistant for a priced plan using the balances you already have.

You: I have 60,000 Amex Membership Rewards points. Find one economy seat from LAX to HNL.

Assistant: As of 2026-08-23, the best-priced plan used 16,000 Qatar Avios for the seat, funded through an Amex transfer at 1:1. The result includes the exact transfer steps, total points, and fees. It does not confirm that a seat is available.

That result is dated because transfer ratios and award prices change. Run a new solve, confirm the award seat, and re-check the transfer terms before moving points.

The dataset

The data/ directory provides a dated slice of the rewards graph and worked solver output.

data/transfer-ratios-current.csv

This file contains 109 bank-to-program transfer edges from eight source currencies, as observed on 2026-08-23.

Each row represents the most recent observation AwardMath had verified against a program page or corroborated across independent sources. Editorial claims that had not been verified were excluded.

Columns include:

• Transfer ratio
• Fees
• Transfer time, where observed
• Verification status
• Date observed

Ratios change. Treat every row as valid only as of its observed date, then re-check the program before transferring points.

data/sample-solved-plans.json

This file contains five scenarios run through the live solver on 2026-08-23.

Four scenarios produced plans. They include:

• LAX to HNL in economy with 60,000 Amex Membership Rewards points
• SFO to HND in business with 100,000 Amex Membership Rewards points, priced through ANA at 82,500 points

One scenario is deliberately empty. The YVR to DXB business search shows how the solver responds when the graph cannot price a route. It names the missing graph coverage instead of inventing a plan.

What is not included

The dataset is a snapshot, not the full AwardMath product.

The versioned history behind it stays at awardmath.com. That history tracks ratios and charts over time and supports price-history and book-now-or-wait calls. It is not included in this repository.

What this will not do

The server does not check live award-seat availability.

Plans are priced from published award charts and transfer relationships. A route can be mathematically valid while having no seats available on your dates.

Before you move any points:

1. Confirm the award space through Seats.aero, PointsYeah, or the airline.
2. Check the points price and cash charges with the booking program.
3. Re-check the transfer ratio and terms.

Transfers are irreversible. Do not transfer because the solver found a priced path. Transfer only after you have confirmed that the seat can be booked.

AwardMath verifies the math. You confirm the seat.

Licenses

The code is licensed under the MIT License.

The files under data/ are licensed under CC BY 4.0. Use this attribution with a link:

Data: AwardMath

Sources:

• AwardMath
• awardmath-mcp repository