# ReferralHero MCP by usefulapi

> ReferralHero MCP by usefulapi is an MCP server. Read ReferralHero campaigns, subscribers, referrals and rewards; add subscribers and points. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Website:** https://usefulapi.io/referralhero/
- **Repository:** https://github.com/m190/usefulapi-mcp/tree/HEAD/servers/referralhero
- **MCP Registry name:** io.usefulapi/referralhero
- **Listing updated:** 2026-11-13

## About

Read ReferralHero campaigns, subscribers, referrals and rewards; add subscribers and points.

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http referralhero https://referralhero.usefulapi.io/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://referralhero.usefulapi.io/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "referralhero": {
      "url": "https://referralhero.usefulapi.io/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "referralhero": {
      "type": "http",
      "url": "https://referralhero.usefulapi.io/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "referralhero": {
      "serverUrl": "https://referralhero.usefulapi.io/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "referralhero": {
      "type": "http",
      "url": "https://referralhero.usefulapi.io/mcp"
    }
  }
}
```

## Tools

- `referralhero_list_campaigns`: List the active ReferralHero campaigns (lists) in the account: uuid, name, subscriber count and creation time. The uuid is needed by every other tool. 10 per page. GET /lists.
- `referralhero_get_leaderboard`: The leaderboard of a campaign: its top subscribers (10 to 100) with referral counts, points and position. GET /lists/{uuid}/leaderboard.
- `referralhero_list_campaign_rewards`: The rewards configured for a campaign (title, description, referrals needed to win each). This is the reward setup, not who earned what: see referralhero_list_unlocked_rewards for that. GET /lists/{uuid}/bonuses.
- `referralhero_create_campaign`: WRITE: create a new ReferralHero campaign (list) with a name and a default referral URL. It adds a campaign and changes nothing existing. POST /lists.
- `referralhero_list_subscribers`: List the subscribers of a campaign, 50 per page, with referral code, referral link, points, position, people referred, status and referrer. Sort and filter by the extra fields. GET /lists/{uuid}/subscribers.
- `referralhero_get_subscriber`: One subscriber by id: contact data, referral code and link, points, position, referrals by level, status, fraud risk level, tags. Only verified subscribers are found. GET /lists/{uuid}/subscribers/{id}.
- `referralhero_get_subscriber_by_email`: Find one subscriber of a campaign by email. Only verified subscribers are found. GET /lists/{uuid}/subscribers/retrieve_by_email.
- `referralhero_get_subscriber_by_referral_code`: Find the subscriber who owns a referral code (the mwr value in a referral link). Only verified subscribers are found. GET /lists/{uuid}/subscribers/retrieve_by_mwr.
- `referralhero_search_subscribers_by_name`: Search subscribers by name across all campaigns of the account, 50 per page. GET /subscribers/search_by_name.
- `referralhero_list_referrals`: The people a subscriber referred, 50 per page. scope: all (pending, unconfirmed and confirmed, default), level_1_confirmed, level_2_confirmed, level_3_confirmed (confirmed only, by referral level), level_2_all or level_3_all (every status at that level). GET /lists/{uuid}/subscribers/{id}/{referred|level_N_referrals|level_N_all_referrals}.
- `referralhero_list_unlocked_rewards`: Rewards unlocked by subscribers across a whole campaign: reward name, status (sent, resent, canceled, pending, flagged), value, subscriber email and id, coupon code, transaction. Filter by status to find rewards still to pay out. GET /lists/{uuid}/rewards.
- `referralhero_list_subscriber_rewards`: Rewards one subscriber has unlocked, with status, value and coupon code. The reward id is what referralhero_update_reward_status needs. GET /lists/{uuid}/subscribers/{id}/rewards.
- `referralhero_list_coupon_groups`: Coupon groups of a campaign (id, name, active flag, coupons with availability), 50 per page. GET /lists/{uuid}/coupon_groups.
- `referralhero_get_coupon_group`: One coupon group with all its coupons (code, available, sent_at). GET /lists/{uuid}/coupon_groups/{id}.
- `referralhero_add_subscriber`: WRITE: add a subscriber (or a referred person) to a campaign. Give the campaign's unique identifier (email, phone, wallet or custom id). By default ReferralHero sends the subscriber a confirmation (double opt-in) email and any welcome automation of the campaign: set double_optin=false to suppress the confirmation email. Set referrer (a referral code or the referrer's email) to credit a referral. P
- `referralhero_update_subscriber`: WRITE: change fields of a subscriber (overwrites the given fields): name, contact identifiers, extra fields, points (contest campaigns), tags, address, referral status (qualified/unqualified). Only fields you pass change. Only verified subscribers can be updated. POST /lists/{uuid}/subscribers/{id}.
- `referralhero_delete_subscriber`: WRITE, DESTRUCTIVE: permanently delete a subscriber from a campaign, with their referral standing. This cannot be undone. DELETE /lists/{uuid}/subscribers/{id}.
- `referralhero_add_points`: WRITE: add points to an existing subscriber (not idempotent: each call adds again). May unlock point-based rewards. The subscriber is identified by the campaign's unique identifier. POST /lists/{uuid}/subscribers/add_points.
- `referralhero_track_transaction`: WRITE: record a purchase/transaction for a subscriber (amount required) so revenue-based rewards and reports count it (not idempotent unless a transaction_id is reused). The subscriber is identified by the campaign's unique identifier. POST /lists/{uuid}/subscribers/add_transactions.
- `referralhero_confirm_referral`: WRITE: confirm a verified referral when its third conversion event happens (campaigns whose goal tracks three events; otherwise ReferralHero returns an error). Confirming can unlock the referrer's rewards and send reward emails. Identify the referral by subscriber_id, or by the campaign's unique identifier. POST /lists/{uuid}/subscribers/{id}/confirm or /subscribers/confirm.
- `referralhero_track_conversion_event`: WRITE: report a conversion event for a referral (campaigns whose goal tracks two or three events). Updates the referral from pending to confirmed (two events) or unconfirmed (three). If the referral is unknown but a referrer is given, the referral is created. May unlock rewards. POST /lists/{uuid}/subscribers/track_referral_conversion_event.
- `referralhero_qualify_referral`: WRITE: mark a referral as qualified, so it counts toward the referrer's rewards. POST /lists/{uuid}/subscribers/{id}/qualify.
- `referralhero_unqualify_referral`: WRITE: mark a referral as unqualified (for example fraud or a refund), so it no longer counts toward the referrer's rewards. POST /lists/{uuid}/subscribers/{id}/unqualify.
- `referralhero_promote_subscriber`: WRITE: promote a subscriber to the campaign's winners list (contests and giveaways). Only verified subscribers can be promoted; an already promoted subscriber returns an error. POST /lists/{uuid}/subscribers/{id}/promote.
- `referralhero_unlock_promoted_reward`: WRITE: unlock a promoted-winner or one-off reward for a subscriber. This delivers the reward and may email the subscriber and use coupon codes. POST /lists/{uuid}/subscribers/{id}/unlock_promoted_reward.
- `referralhero_update_reward_status`: WRITE: set the status of an unlocked reward to sent, resent or canceled. Marking sent/resent can trigger the reward delivery email to the subscriber. Get the reward_id from referralhero_list_subscriber_rewards or referralhero_list_unlocked_rewards. POST /lists/{uuid}/subscribers/update_reward_status.
- `referralhero_create_coupon_group`: WRITE: create a coupon group for a campaign, optionally with its first coupon codes. It only adds a group. POST /lists/{uuid}/coupon_groups.
- `referralhero_add_coupons`: WRITE: add coupon codes to an existing coupon group. It only adds codes. POST /lists/{uuid}/coupons.

## FAQ

### How do I add ReferralHero MCP by usefulapi to Claude Code?

Run this command in your terminal: claude mcp add --transport http referralhero https://referralhero.usefulapi.io/mcp

---
Source: https://ai-powered.com/mcp/referralhero-mcp-by-usefulapi
