Servidor MCP de AwardMath

awardmath-mcp conecta asistentes de IA a la API pública de AwardMath mediante el Model Context Protocol.

AwardMath es el optimizador de puntos de viaje. Tú proporcionas tus saldos de puntos y un objetivo de viaje. Un solucionador determinista busca en un grafo versionado de ratios de transferencia y tablas de canje, y devuelve hasta tres planes de canje verificados y explicables.

Los cálculos consisten en enumerar y puntuar sobre las tablas publicadas. Un LLM puede interpretar tu pregunta y explicar los resultados, pero nunca elige ni optimiza los planes.

Este repositorio contiene el servidor MCP y una instantánea gratuita de datos en data/. El servidor es de solo lectura. No requiere tarjeta de API, inicio de sesión ni suscripción, y no hace scraping de sitios de aerolíneas.

Herramientas

El servidor expone tres herramientas.

list_programs

list_programs devuelve todos los programas que AwardMath rastrea e identifica qué IDs de programa se pueden gastar hoy en una ejecución.

Los programas gastables incluyen programas de canje con tablas tarifadas y monedas bancarias que se transfieren a uno de esos programas. Esta distinción evita que un asistente le pida al solucionador gastar un saldo que no tiene ningún camino hacia un canje con precio.

solve_award_trip

solve_award_trip busca planes que encajen con tu cartera, orígenes, destinos, cabinas, número de viajeros y tope de efectivo.

Si se obtiene una respuesta correcta, contiene hasta tres planes con:

• Pasos exactos de transferencia

• Puntos totales requeridos

• Cargos tarifados

Si ningún plan encaja, la respuesta incluye no_plan_reasons. Estos motivos identifican la restricción que ha fallado, en lugar de rellenar el hueco con una ruta o un precio inventado.

parse_wallet

parse_wallet convierte texto libre en saldos con estructura.

Por ejemplo:

250k Amex, 80k Chase

Los saldos claros se convierten en IDs de programa y cantidades. Las expresiones ambiguas se muestran para aclararlas, en lugar de asignarlas a un programa por conjetura.

Configuración

Puedes ejecutar el servidor directamente desde GitHub o instalarlo desde un clon.

Claude Code

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

Claude Desktop u otro cliente MCP configurado con JSON

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

Desde un clon

pip install -e .
awardmath-mcp

No se requiere ninguna clave de API ni cuenta en AwardMath.

Ejemplo

Pide a tu asistente un plan tarifado con los saldos que ya tienes.

Tú: Tengo 60.000 puntos de Amex Membership Rewards. Encuentra un asiento en clase económica de LAX a HNL.

Asistente: A fecha de 2026-08-23, el plan con mejor precio usó 16.000 Avios de Qatar para el asiento, financiado a través de una transferencia de Amex a 1:1. El resultado incluye los pasos exactos de transferencia, el total de puntos y los cargos. No confirma que el asiento esté disponible.

Ese resultado tiene una fecha asociada porque los ratios de transferencia y los precios de los canjes cambian. Ejecuta una nueva búsqueda, confirma el asiento de canje y revisa las condiciones de transferencia antes de mover los puntos.

El conjunto de datos

El directorio data/ ofrece una instantánea fechada del grafo del programa de puntos y la salida ya calculada del solucionador.

data/transfer-ratios-current.csv

Este archivo contiene 109 aristas de transferencia banco-progr desde ocho monedas de origen, observadas el 2026-08-23.

Cada fila refleja la observación más reciente que AwardMath ha verificado contra la página del programa o ha corroborado entre fuentes independientes. Las afirmaciones editoriales que no se habían verificado quedaron excluidas.

Las columnas incluyen:

• Ratio de transferencia

• Comisiones

• Tiempo de transferencia, cuando se observa

• Estado de verificación

• Fecha de observación

Los ratios cambian. Trata cada fila como válida solo en la fecha de observación correspondiente y vuelve a consultar el programa antes de transferir puntos.

data/sample-solved-plans.json

Este en archivo contiene cinco escenarios ejecutados con el solucionador en directo el 2026-08-23.

Cuatro de esos escenarios han producido planes. Entre ellos:

• LAX a HNL en clase económica con 60.000 puntos de Amex Membership Rewards

• SFO a HND en clase business con 100.000 puntos de Amex Membership Rewards, tarifado mediante ANA a 82.500 puntos

Uno es deliberadamente vacío. La búsqueda de YVR a DXB en clase business muestra cómo responde el solucionador cuando el grafo no puede dar precio a una ruta. En su lugar, indica la cobertura del grafo que falta en vez de inventar un plan.

Qué no se incluye

El conjunto de datos es una instantánea, no el producto AwardMath completo.

El historial versionado que lo acompaña queda en awardmath.com. Este historial registra ratios y tarifas a lo largo del tiempo y sirve para consultar el historial de precios y de reservar ahora o esperar. It is not other in this repo.

Lo que este servidor no hará

El servidor no comprueba la disponibilidad de asientos de canje en tiempo real.

Los planes se valoran a partir de tablas de canje públicas y de relaciones de transferencia publicadas. Una ruta puede ser matemáticamente valida pero no tener asientos disponibles en tus fechas.

Antes de mover ningún punto:

1. Confirma el espacio del canje mediante Seats.aero, PointsYeah, e o la aerolínea.

2. Comprueba el precio en puntos y el importe en efectivo en la tabla del programa con el que quieres reservar.

3. Vuelve a consultar el ratio y las condiciones de la transferencia.

Las transferencias son irreversibles. No transfieras solo porque el solucionador haya encontrado un camino con precio. Transfiere únicamente después de haber confirmado que el asiento se puede reservar.

AwardMath comprueba los cálculos. Tú confirma el asiento.

Licencias

El código está publicado bajo la Licencia MIT.

Los archivos que hay en data/ están publicados bajo CC BY 4.0. Usa esta atribución con un enlace:

Datos: Datos y canje

Fuentes:

• AwardMath

• Repositorio awardmath-mcp