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.

Related MCP server: ripio-community-mcp

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

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:

Paid-API credentials are username:password. Inputs are validated against schemas transcribed from AwardWallet's documentation, and only the validated value is sent.

Current gaps:

• Security-question and one-time-code answers can't be supplied yet.

• The Email Parsing browser-redirect endpoint isn't included.

• The travel timeline covers connected users only.

Secure input page

call_api_write_operation never accepts a password or token as an argument. It returns a one-time link like http://127.0.0.1:<port>/secure/<token>: the user types the secret there, the server sends it straight to AwardWallet, and get_secure_input_result returns the response.

How the page protects secrets:

• It listens on 127.0.0.1 only and validates Host, Origin and Sec-Fetch-Site.

• It runs no scripts.

• It shows where the secret will be used, and asks for confirmation before sending a password without TLS.

• Links are single-use and expire after 15 minutes.

• Secrets are never logged or stored, and they're redacted from anything returned.

To reach the page on a remote host:

1. Set AW_SECURE_INPUT_PORT, then forward it (SSH tunnel, Tailscale Serve).

2. Set AW_SECURE_INPUT_URL to the forwarded address, so the links use it.

Found a vulnerability? See SECURITY.md.

Configuration

Limits

• Rate limit. AwardWallet allows 20 requests per rolling 10 minutes for each user, member or account. The server caches identical reads for a minute. It fetches accounts for up to 30 people per call; peopleOffset pages through larger businesses.

• Result size. Results are capped at 60,000 characters, with valid-JSON truncation and pagination (limit, historyOffset, pageToken).

Develop and release

npm test            # unit + end-to-end tests (demo data, no network, no credentials)
npm run typecheck
npm run inspect     # MCP Inspector against the build (set AW_MOCK_MODE=true for demo data)
npm run pack:mcpb   # dist/awardwallet-mcp.mcpb
npm run pack:plugin # build/plugin-marketplace: plugin marketplace for ChatGPT, Codex and Claude

To release, bump the version in package.json, mcpb/manifest.json, plugin-src/plugin.json, plugin-src/.claude-plugin/plugin.json and src/server.ts, then push a matching tag (for example v0.2.0). The release workflow tests and builds, attaches awardwallet-mcp.mcpb and awardwallet-mcp.mjs to a new GitHub release, and publishes the plugin to the plugin branch that ChatGPT and Claude install from.

The plugin's launchers (plugin-src/scripts/; Claude refuses plugins with a top-level bin/ in chat and Cowork) run the server with the Node.js runtime that ships with ChatGPT and Codex, and fall back to a Node.js on PATH.

Contributing

Issues and pull requests are very welcome: bugs, questions, ideas, docs or code. Start by opening an issue; CONTRIBUTING.md covers setup, conventions and the PR checklist.

Some ideas where help would be great:

• Answering AwardWallet security questions and one-time codes through the secure input page

• Letting the Claude Desktop extension read keys saved with login

• Better summaries for more itinerary types, and more providers' date formats

• Real-world reports of what your accounts look like through the tools, and what's missing

Please don't include API keys, passwords or personal loyalty data in issues or tests.

License

MIT. Not affiliated with AwardWallet. "AwardWallet" is a trademark of its owner.