# AwardMath MCP server

`awardmath-mcp` connects AI assistants to the public [AwardMath](https://awardmath.com) 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:

```text
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

```json
{
  "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-27, the best-priced plan used 12,500 Aeroplan points for the seat on a partner award, 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 six scenarios run through the live solver on 2026-08-27.

Five 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 55,000 points
- YVR to DXB in business with 350,000 Aeroplan points, priced at 90,000 points on a partner award

One scenario is deliberately empty. The DFW to CUN economy 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](https://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](https://awardmath.com)

Sources:

- [AwardMath](https://awardmath.com)
- [awardmath-mcp repository](https://github.com/DanCastHub/awardmath-mcp)