AwardWallet MCP

Ask Claude or ChatGPT about your airline miles, hotel points and credit-card rewards tracked in AwardWallet:

• "Which of my points, certificates or elite statuses expire before December 31?"
• "What's my Marriott balance and status, and how many nights until the next level?"
• "Show the last 50 transactions on my Delta account."
• "What trips do we have coming up, with confirmation numbers?"
• "Which accounts have update problems?"

It runs on your own computer, and your AwardWallet key stays there.

Unofficial. This project is not affiliated with or endorsed by AwardWallet. It uses AwardWallet's published APIs with a key you create.

Get started (no coding needed)

Step 1: Get your AwardWallet API key

You need an AwardWallet account with AwardWallet Plus. The API key comes from a free AwardWallet Business account linked to your personal account; you sign in to both with the same login.

1. Sign in to AwardWallet, then open Create a business account.
2. Give the business access to your loyalty accounts. On the business site (business.awardwallet.com), click Members at the top, then Request full access.
3. Approve the request. AwardWallet emails you a link to authorize it. Once you approve, all your loyalty accounts are shared with the business, including ones you add later. Until then the business lists you with no accounts, and your assistant will find nothing.
4. Optional: add family. On the business site, use Members → Add new member to invite them. Each person approves in their own AwardWallet account and chooses how much to share; "Read all" is enough for this app.
5. Copy your API key from business.awardwallet.com/profile/api.

Step 2: Add it to your AI app

Claude Desktop

Works on Windows and Mac. Claude Desktop includes everything needed to run it.

1. Download awardwallet-mcp.mcpb.
2. Double-click the file. You can also drag it onto the Claude Desktop window, or use Settings → Extensions → Advanced settings → Install Extension…
3. Paste your API key when asked, then finish the installation.
4. Ask Claude: "Which of my AwardWallet points or certificates expire this year?"

To change the key later, go to Settings → Extensions → AwardWallet → Configure.

Claude Code and Cowork

The same plugin as for ChatGPT, without downloading anything. It works in Claude Code (the Claude Desktop Code tab, the terminal and VS Code) and in Cowork. Regular Claude chats can't run plugins that run on your computer; use the Claude Desktop extension for those.

1. Add the marketplace bbarabe/awardwallet-mcp:
   • Claude Desktop: Customize → Plugins → Add → Add marketplace, then enter it as the URL.
   • Terminal: claude plugin marketplace add bbarabe/awardwallet-mcp
2. Add AwardWallet from the plugin list (terminal: claude plugin install awardwallet@awardwallet-mcp).
3. Start a new session and ask Claude to "set up AwardWallet". It gives you a link to a secure connection page on your computer.
4. Paste your API key on that page and select Check and save. Then tell Claude you're done.

Needs Node.js 20.10 or later, unless the ChatGPT desktop app is installed: the plugin uses ChatGPT's copy of Node when it finds one.

ChatGPT desktop app

Works on Windows and Mac, in the ChatGPT desktop app's Codex and Work modes. ChatGPT includes everything needed to run it.

1. In ChatGPT, open Plugins in the sidebar, then choose Add → Add a marketplace.

2. Fill in:

   • Source: bbarabe/awardwallet-mcp
   • Git ref: plugin

   Then select Add marketplace.

3. Search the plugins for AwardWallet, open it and select Install plugin.

4. Select Set up AwardWallet. ChatGPT checks the connection and gives you a link to a secure connection page that opens on your computer.

5. Paste your API key on that page and select Check and save. Then tell ChatGPT you're done.

6. Ask ChatGPT: "Which of my points, certificates or elite statuses expire in the next 90 days?"

To change the key later, ask ChatGPT to "connect AwardWallet again".

To update to a new version, open Settings → Plugins → Marketplace, select Upgrade next to AwardWallet MCP, then restart ChatGPT. To uninstall, select the delete icon there instead; your saved key stays on your computer in case you reinstall.

Try it first with sample data

You don't need an AwardWallet key to see how it works. Demo mode uses a made-up family with eight accounts, a few certificates and some trips, and sends nothing to AwardWallet.

• Claude Desktop: leave the API key empty and switch on Demo mode in the extension's settings.
• ChatGPT: the plugin has no settings screen, so use the developer setup with AW_MOCK_MODE=true.

Good to know

• Balances aren't live. They're AwardWallet's latest update of each account; results show when that was.
• What each person shares matters. Their sharing level ("Read numbers", "Read balances" or "Read all") controls what you see.
• Free (non-Plus) AwardWallet members show less. Their history and expiration dates stay hidden unless the Business account has a paid subscription.
• Trips need more. The travel timeline needs a paid Business subscription and AwardWallet's approval.
• Privacy:
  • The app runs on your computer and talks only to AwardWallet.
  • Your key stays on your computer: in Claude Desktop's secure settings, or for ChatGPT, in a settings file in the plugin's private folder.
  • Keys and passwords are never typed into the chat; a one-time page opens on your computer for them.
• Read-only mode. Add AW_READ_ONLY = true (Claude Desktop: the Read-only switch) to let the assistant look but never change anything. It's a good idea with autonomous agents.

Something not working? Open an issue. Please don't include your API key or personal details.

For developers

Build from source

Requires Node.js 20.10 or later.

git clone https://github.com/bbarabe/awardwallet-mcp.git
cd awardwallet-mcp
npm install
npm run build        # dist/awardwallet-mcp.mjs

Save the API key in your OS credential store (Windows Credential Manager, macOS Keychain or Linux Secret Service). login checks the key with AwardWallet first; status shows what it can see:

node dist/awardwallet-mcp.mjs login
node dist/awardwallet-mcp.mjs status

Credentials are resolved in this order:

1. environment variable (AW_API_KEY);
2. AW_API_KEY_FILE;
3. the credential store;
4. the settings file written by connect_awardwallet's secure page: credentials.json in the plugin's data folder (PLUGIN_DATA) when running as a ChatGPT/Codex plugin, otherwise in %APPDATA%wardwallet-mcp (Windows), ~/Library/Application Support/awardwallet-mcp (Mac) or ~/.config/awardwallet-mcp (Linux). The file is readable only by you.

logout --all removes credentials from the credential store. The Claude Desktop extension and the ChatGPT plugin can't read the credential store (they ship without the native keyring module), so they use their own settings or the settings file.

Connect from the command line

In the commands below, replace /absolute/path/to/awardwallet-mcp with the folder you cloned.

Claude Code:

claude mcp add --scope user awardwallet -- node /absolute/path/to/awardwallet-mcp/dist/awardwallet-mcp.mjs

Codex CLI (shares ~/.codex/config.toml with the ChatGPT desktop app). Install the published plugin:

codex plugin marketplace add bbarabe/awardwallet-mcp --ref plugin
codex plugin add awardwallet@awardwallet-mcp

Or run your build as a plain MCP server:

codex mcp add awardwallet -- node /absolute/path/to/awardwallet-mcp/dist/awardwallet-mcp.mjs

To try an unreleased plugin build, run npm run pack:plugin and add build/plugin-marketplace as a marketplace: in ChatGPT with Plugins → Add → Add a marketplace or codex plugin marketplace add, in Claude Code with claude plugin marketplace add.

OpenClaw:

openclaw mcp add awardwallet --command node --arg /absolute/path/to/awardwallet-mcp/dist/awardwallet-mcp.mjs

For an autonomous agent, set AW_READ_ONLY=true. On a headless Linux machine without a keyring, pass AW_API_KEY through the agent's secret mechanism or AW_API_KEY_FILE.

Claude Desktop without the extension: add a server to claude_desktop_config.json with command node and the path to dist/awardwallet-mcp.mjs as its argument. That server reads the key saved by login.

Any other MCP client: it's a standard stdio server. Run node dist/awardwallet-mcp.mjs.

Demo data: use AW_MOCK_MODE=true anywhere, for example claude mcp add awardwallet-demo -e AW_MOCK_MODE=true -- node ….

Tools

| Tool | Access | What it does | |---|---|---| | get_status | read | Which APIs are configured (and where the credentials come from), demo/read-only mode, people and account counts | | list_people | read | Connected AwardWallet users and business members, with ids and sharing levels | | list_loyalty_accounts | read | Balances, elite status, update problems and everything that expires (points, certificates and other sub-accounts, elite status). Filter by person, program, type, balance, or an expiringBy date. | | get_loyalty_account | read | One account's properties, sub-accounts, update links and paginated transaction history | | get_travel_timeline | read | Reservations in a date window: flights, hotels, cars, trains, cruises, events and more | | search_loyalty_programs, get_loyalty_program | read | Programs AwardWallet supports and what it tracks for each | | search_api_operations | read | Finds raw API operations and returns their input schemas | | call_api_read_operation | read | Runs a read-only raw operation | | call_api_write_operation | write | Runs a raw operation that changes data, signs in to a loyalty or mailbox account, or costs money | | get_secure_input_result | read | Result of a request completed on the secure input page | | connect_awardwallet | write | Link to the secure input page where the user enters the API key (or a paid API's credentials); saves them to the settings file and uses them right away | | create_connection_link | write | (opt-in, AW_CONNECT_LINKS=true) Creates an AwardWallet invitation link; needs AwardWallet's approval |

Every tool has readOnlyHint/destructiveHint annotations, and read-only mode doesn't register the write tools.

Every AwardWallet API

Besides the free Account Access API, AwardWallet sells APIs by contract. Add their credentials to enable them in the catalog tools:

| API | Operations | Credential (login --api <id> or environment variable) | |---|---|---| | Account Access | 10 | accountAccess / AW_API_KEY | | Web Parsing (Loyalty) | 9 | webParsing / AW_WEB_PARSING_CREDENTIALS | | Email Parsing | 16 | emailParsing / `AW_EMAIL