Skip to main content
Glama
tremendous-mcp

tremendous-mcp

by Bryan21B

tremendous-mcp

An MCP server for the Tremendous rewards API. Use it to send rewards from an AI assistant, see who has received rewards, and manage orders that need approval.

The server runs on your computer over stdio. It works with Claude Desktop, Claude Code and other MCP clients. Two tools also show interactive views in clients that support MCP Apps.

This project is not affiliated with Tremendous.

Features

  • Send rewards to one or more recipients (email, SMS or link delivery), with a campaign or a list of products.

  • See who received rewards: one summary for each recipient (number of rewards, total, last date), with filters for email, name, dates, campaign and delivery status.

  • Fix failed deliveries: resend a reward (optionally to a corrected email or phone), or cancel it.

  • Approve or reject orders in PENDING APPROVAL.

  • Read the account: organization, funding sources and balance, product catalog, campaigns, orders.

  • Interactive views (MCP Apps): a rewards dashboard and an editable send form.

  • Sandbox by default: the server uses the Tremendous sandbox (fake money) until you set TREMENDOUS_ENV=production.

Related MCP server: Africa’s Talking MCP

Requirements

  • Node.js 20.11 or later.

  • A Tremendous account with admin access, to register an OAuth app.

  • Optional: the 1Password CLI, if you want to keep the client secret out of your shell environment.

Setup

1. Register a Tremendous OAuth app

Start in the sandbox: https://testflight.tremendous.com.

  1. Go to Team settings → Developers → Developer apps and click Register app.

  2. Set the redirect URI to https://localhost:8787/callback. Tremendous accepts only https redirect URIs. No server has to run at this address (see step 3).

  3. Keep the client ID and the client secret.

For production, register a second app at https://api.tremendous.com.

2. Install and build

git clone https://github.com/Bryan21B/tremendous-mcp.git
cd tremendous-mcp
npm install
npm run build

3. Log in

Give the client credentials to the login script in one of these two ways.

Option A: environment variables:

export TREMENDOUS_CLIENT_ID=...
export TREMENDOUS_CLIENT_SECRET=...
npm run login

Option B: 1Password references:

cp .env.op.example .env.op   # then edit the op:// paths
op run --env-file=.env.op -- npm run login

The login opens your browser:

  1. Log in to Tremendous and allow access.

  2. Tremendous sends the browser to https://localhost:8787/callback. The script listens there with a self-signed certificate (it makes one with openssl the first time, in ~/.config/tremendous-mcp/tls/). The browser warns that the connection is not private: click Advanced, then Proceed to localhost.

  3. The page says "Code received", and the script continues by itself.

If that does not work (for example, openssl is not installed), copy the callback address, which starts with https://localhost:8787/callback?code=, go back to the terminal and press Enter. The script reads the address from the clipboard, or you can paste it. Chrome can keep the Tremendous address in the address bar when the redirect fails. In that case, find the callback address in chrome://history.

The script then shows "Connected to: ".

The script writes the tokens to ~/.config/tremendous-mcp/tokens.<env>.json, with mode 0600. Tremendous refresh tokens are single-use. The server refreshes them under a file lock, so two clients can run the server at the same time.

Reading the clipboard uses pbpaste (macOS). On other systems, paste the address into the terminal.

4. Add the server to your MCP client

The server needs the client credentials at run time, because it refreshes the tokens.

Claude Code

claude mcp add tremendous -s user \
  -e TREMENDOUS_ENV=sandbox \
  -e TREMENDOUS_CLIENT_ID=... \
  -e TREMENDOUS_CLIENT_SECRET=... \
  -- node /absolute/path/to/tremendous-mcp/build/index.js

Claude Desktop (claude_desktop_config.json, in mcpServers)

"tremendous": {
  "command": "node",
  "args": ["/absolute/path/to/tremendous-mcp/build/index.js"],
  "env": {
    "TREMENDOUS_ENV": "sandbox",
    "TREMENDOUS_CLIENT_ID": "...",
    "TREMENDOUS_CLIENT_SECRET": "..."
  }
}

With 1Password, do not put the secrets in the configuration file. Launch through op run instead:

"tremendous": {
  "command": "op",
  "args": ["run", "--env-file=/absolute/path/to/tremendous-mcp/.env.op", "--",
           "node", "/absolute/path/to/tremendous-mcp/build/index.js"],
  "env": { "TREMENDOUS_ENV": "sandbox" }
}

Claude Desktop does not use your shell PATH. If it cannot find op or node, use the full path (for example /opt/homebrew/bin/op). Restart Claude Desktop after you change the file.

Tools

Tool

Type

What it does

get_account

read

Organization, environment, funding sources and balance

list_funding_sources

read

Balance, cards, bank accounts, invoice

list_products

read

Reward catalog. Filter by country, currency, name and category

list_campaigns, get_campaign

read

Campaigns (reward templates)

list_orders, get_order

read

Orders. Filter by date, campaign, external_id and status

get_reward

read

One reward and its delivery status

list_rewards

read + view

Who received rewards. Filter by email, name, dates, campaign and delivery status

review_rewards

read + view

Check a batch and show the send form. This tool sends nothing

send_rewards

write

Send rewards. Makes one order for each recipient

resend_reward

write

Resend after a delivery failure

cancel_reward

write

Cancel a reward that is not redeemed

generate_reward_link

write

New redemption link (LINK rewards only). Anyone with the link can redeem the reward

approve_order, reject_order

write

Orders in PENDING APPROVAL. Requires "Allow approvals via API" in Tremendous

The typical flow to send rewards is review_rewards, then the user checks the draft, then send_rewards with the same draft_id.

Interactive views (MCP Apps)

  • Rewards dashboard (list_rewards): totals, search, delivery-status filters, a "by recipient" or "all rewards" table, Resend and Cancel buttons on failed rewards, and Load more for older rewards.

  • Send form (review_rewards): edit the recipients, amounts, campaign, funding source, delivery method and message, then click Send and Confirm. The form then shows the result for each recipient.

All tools also return a text summary, for clients that do not show the views.

Safety

  • Sandbox first. The default environment is the sandbox. Each tool result shows SANDBOX or PRODUCTION.

  • Write tools are marked. Tools that spend money or cannot be undone have destructiveHint: true. Most clients then ask you before each call. This does not occur if you select "Always allow". Do not select "Always allow" for the write tools.

  • Buttons in the views call tools directly. Your client may not ask you first. In the send form, the two clicks (Send, then Confirm) are the only check.

  • No double payments on retry. send_rewards gives each reward the Tremendous external_id mcp-<draft_id>-<hash of the recipient>. The hash comes from the email, else the phone, else the name. If you send the same draft again, Tremendous returns the existing order for each recipient who was already paid. This is also true if you remove, reorder or add recipients. If you change the amount for a recipient who was already paid, Tremendous returns a 409 conflict and does not make a second payment.

  • Insufficient funds stop the batch. After a 402 response, the server does not try the remaining recipients.

  • No step-up authentication. The OAuth login gives full access within the granted scope.

Configuration

Variable

Default

Use

TREMENDOUS_ENV

sandbox

sandbox (testflight.tremendous.com) or production (api.tremendous.com)

TREMENDOUS_CLIENT_ID, TREMENDOUS_CLIENT_SECRET

none

OAuth app credentials

TREMENDOUS_SCOPES

default

OAuth scopes

TREMENDOUS_REDIRECT_URI

https://localhost:8787/callback

Must be the same as the redirect URI of the app

TREMENDOUS_TOKEN_DIR

~/.config/tremendous-mcp

Folder for the token files

Use production

  1. Register an app at https://api.tremendous.com with the same redirect URI.

  2. Log in with the production credentials: TREMENDOUS_ENV=production npm run login.

  3. Set TREMENDOUS_ENV=production in your MCP client configuration.

The sandbox and production use different token files, so you can keep both.

Notes and limitations

  • Recipient search scans rewards. The Tremendous API cannot filter rewards by recipient. list_rewards reads up to max_scan rewards (default 5,000, 500 for each request) and filters them. With a date range or a campaign, the tool reads orders instead, because the API can filter orders by date and campaign. If the result is truncated, call the tool again with offset=next_offset, or click Load more in the dashboard.

  • One order for each reward. The Tremendous API requires this. A batch of N recipients makes N requests, one after the other.

  • Not verified yet:

    • PKCE support. The login does not use PKCE.

    • Whether the default scope is sufficient for order approvals.

Development

Command

What it does

npm run build

Compile the server to build/ and bundle each view into one HTML file in dist/

npm test

Unit and contract tests with a fake Tremendous API (no network)

npm run typecheck

Type-check the server and the views

npm run lint

Biome lint and format check (npm run lint:fix fixes)

npm run check

Lint, typecheck, tests and build (what CI and the pre-push hook run)

npm run login

Interactive OAuth login

npm run smoke -- <email> [campaign_id]

Live test against the sandbox only: sends a 1.00 reward to <email>

Project layout:

src/
  index.ts          stdio entry point
  server.ts         MCP server: tools and UI resources
  tools/read.ts     read-only tools (including the two view tools)
  tools/write.ts    tools that spend money or cannot be undone
  rewards-query.ts  paging and filtering for list_rewards
  client.ts         REST client: refresh on 401, backoff on 429, readable errors
  token-store.ts    token file, locked single-use refresh
  login.ts          OAuth login script
ui/                 MCP Apps views (plain TypeScript and CSS, bundled with Vite)
test/               Vitest tests and a fake Tremendous API

Releases and versioning

This project uses Semantic Versioning. The version in package.json is the single source of truth. The server reports it to MCP clients, and the views use it too.

Releases are automatic. On each push to main, CI runs the checks. If they pass, semantic-release reads the commit messages since the last tag. It then sets the next version, updates CHANGELOG.md and package.json, tags v<version> and makes the GitHub release.

Commit messages must follow Conventional Commits. The type sets the version:

Commit type

Release

feat:

minor (0.x.0)

fix:, perf:

patch (0.x.y)

feat!: or a BREAKING CHANGE: footer

minor while the version is below 1.0.0

docs:, test:, chore:, ci:, refactor:, style:, build:

no release

The public interface is the tool names, their input fields and their results. A change that breaks it is a breaking change.

Git hooks

npm install installs these hooks (husky):

  • commit-msg: rejects a subject that is not a Conventional Commit.

  • pre-commit: Biome on the staged files, then the typecheck.

  • pre-push: a secret scan of the commits to push, then npm run check (lint, typecheck, tests, build).

License

MIT

Available Tools

16 tools
approve_orderApprove orderA
Destructive

Approve an order in status PENDING APPROVAL so Tremendous executes it and sends the reward(s). Needs "Allow approvals via API" in Tremendous Team settings → Order approvals, otherwise Tremendous answers 403. Use list_orders with status "PENDING APPROVAL" to find them.

Inputs: id (required).

cancel_rewardCancel rewardA
Destructive

Cancel a reward and refund its value. Tremendous only allows this for rewards that are not redeemed and not expired (typically after a delivery failure).

Inputs: id (required).

get_accountTremendous accountA
Read-only

Show the connected Tremendous organization, the environment (SANDBOX or PRODUCTION) and the funding sources with their balances. Call this first to know which account you act on.

Inputs: no named parameters.

get_campaignGet campaignB
Read-only

Get one campaign with its products and email settings.

Inputs: id (required).

get_orderGet orderB
Read-only

Get one order with its status, payment and rewards.

Inputs: id (required).

get_rewardGet rewardB
Read-only

Get one reward: recipient, value, delivery method and delivery status.

Inputs: id (required).

list_campaignsList campaignsA
Read-only

List Tremendous campaigns (reward templates with products, message and branding). Use a campaign_id in send_rewards.

Inputs: no named parameters.

list_funding_sourcesList funding sourcesA
Read-only

List the funding sources (balance, card, bank, invoice) that can pay for rewards. Balances in this list can be a little stale.

Inputs: no named parameters.

list_ordersList ordersA
Read-only

List orders, newest first. Filter by creation date range, campaign, external_id, or status (for example PENDING APPROVAL to find orders that wait for approval).

Inputs: limit, since, until, offset, +3 more.

list_productsList reward productsA
Read-only

List the reward products (gift cards, PayPal, Visa, charity, ...) in the catalog. Filter by country/currency and by a name search. Use product IDs in send_rewards.products.

Inputs: limit, search, country, category, +1 more.

list_rewardsWho received rewardsA
Read-only

Find which people received rewards. Filter by recipient email or name (substring), date range, campaign and delivery status. Returns one summary per recipient (count and total) and the reward rows, and shows an interactive table. Tremendous cannot filter by recipient, so this scans up to max_scan rewards (newest first); if truncated is true, call again with offset=next_offset.

Inputs: name, email, since, until, +4 more.

reject_orderReject orderA
Destructive

Reject an order in status PENDING APPROVAL; its rewards are not sent. Needs "Allow approvals via API" in Tremendous Team settings → Order approvals, otherwise Tremendous answers 403. Use list_orders with status "PENDING APPROVAL" to find them.

Inputs: id (required).

resend_rewardResend rewardA
Destructive

Resend a reward email/SMS. Tremendous only allows this after a delivery failure (delivery_status FAILED). Optionally correct the email (EMAIL rewards) or the phone (PHONE rewards), not both.

Inputs: id (required), updated_email, updated_phone.

review_rewardsReview rewards before sendingA
Read-only

Prepare a batch of rewards WITHOUT sending anything. Checks the recipients, amounts, campaign/products and funding source, and shows an editable review form with a Send button. Use this before send_rewards. Returns a draft_id to pass to send_rewards.

Inputs: recipients (required), message, language, products, +7 more.

send_rewardsSend rewardsA
DestructiveIdempotent

SEND rewards: this spends money and emails/texts the recipients. It cannot be undone once a reward is redeemed. Creates one Tremendous order per recipient. Prefer calling review_rewards first and let the user confirm. draft_id makes retries safe: with the same draft_id, a recipient who was already paid is not paid again (even if you remove, reorder or add other recipients), so after a partial failure retry with the same draft_id.

Inputs: draft_id (required), recipients (required), message, language, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 16 tools

    Disambiguation4/5

    Nearly every tool targets a distinct resource plus action (approve vs reject, cancel vs resend vs generate link, review vs send). Minor overlap: get_account already surfaces funding sources with balances, which overlaps list_funding_sources, and list_rewards vs get_reward / list_orders vs get_order are close pairs but distinguished by summary vs single-record and the scan/truncation behavior is well documented.

    Naming Consistency4/5

    All names are snake_case with a predictable verb_noun shape (list_*, get_*, approve_order, send_rewards), so an agent can pattern-match easily. Minor deviation is plurality: the reward-sending tools are plural (send_rewards, review_rewards) while other reward tools are singular (get_reward, cancel_reward, resend_reward), but the pattern is still readable.

    Tool Count4/5

    16 tools is slightly above the typical 3-15 sweet spot but every tool maps to a genuine Tremendous operation (orders, rewards, campaigns, products, funding, account) without gratuitous duplication. The review/send split earns its extra tool by preventing accidental spend.

    Completeness4/5

    The surface covers the full reward lifecycle end-to-end: discover products/campaigns, review, send, retry, resend, regenerate links, cancel, plus order approval/rejection and account/funding context. Gaps are minor: campaigns are read-only (no create/update), and there is no dedicated order-creation or reward-detail search beyond list/get, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to check an application balance and preview or send bulk SMS and airtime, either through a hosted OAuth connection that needs no local install or via a self-hosted stdio/Cloudflare Workers deployment using your own credentials. Sending is preview-only by default and gated behind environment, recipient allowlist, and mutation opt-in settings.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to manage cold-email infrastructure through natural language, covering domain and mailbox provisioning, DNS setup, email warming, inbox and reply triage, exports, pre-warmed domain purchases, and webhooks. Supports hosted OAuth or local stdio installs with scoped read, write, and purchase permissions, plus two-step confirmation for anything that charges a card.
      45 PyPI
      MIT