Which integrations are available for this server?

Supports the creation of Stripe-based promo codes for affiliate campaigns within the FirstPromoter platform.

How do I use FirstPromoter MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FirstPromoter MCP Server list all pending commissions that need approval" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

FirstPromoter MCP Server (Local)

A local MCP (Model Context Protocol) server that connects AI assistants like Claude to your FirstPromoter affiliate management platform. Runs on your machine via Docker or Node.js — your API credentials never leave your device.

Looking for the remote/hosted version? That will be a separate project (coming later).

What is This?

This server acts as a translator between AI assistants and FirstPromoter:

Component	What it Does
MCP Server	Receives requests from AI, returns structured data
Tools	Actions the AI can perform (e.g., "Get Promoters")
Transport	stdio — runs locally on your machine
FirstPromoter API	The data source — your affiliate management platform

Quick Start

Prerequisites

Node.js 20+ installed
A FirstPromoter account with API access
Claude Desktop (for testing)

Step 1: Install Dependencies

cd firstpromoter-mcp
npm install

Step 2: Configure Credentials

Copy the environment template:
```
cp .env.example .env
```
Edit .env and add your FirstPromoter credentials:
- FP_BEARER_TOKEN: Find at Dashboard > Settings > Integrations > Manage API Keys
- FP_ACCOUNT_ID: Find at Dashboard > Settings > Integrations

Step 3: Build & Test

# Build TypeScript
npm run build

# Test locally (loads .env automatically)
npm run dev:stdio

You should see:

FirstPromoter MCP Server running on stdio

Step 4: Connect to Claude Desktop

Option A: Docker (recommended)

Build the Docker image:

docker build -t firstpromoter-mcp .

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "firstpromoter": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "FP_BEARER_TOKEN",
        "-e", "FP_ACCOUNT_ID",
        "firstpromoter-mcp"
      ],
      "env": {
        "FP_BEARER_TOKEN": "your_token_here",
        "FP_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}

Option B: Direct Node.js

{
  "mcpServers": {
    "firstpromoter": {
      "command": "node",
      "args": ["/full/path/to/firstpromoter-mcp/dist/index.js"],
      "env": {
        "FP_BEARER_TOKEN": "your_token_here",
        "FP_ACCOUNT_ID": "your_account_id_here"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Step 5: Try It Out

Ask Claude:

"List my promoters"
"Show me promoters sorted by revenue"
"Show all commissions for this month"
"Get a campaign performance report for Q1"
"List all promo codes"

Available Tools (43 total)

Promoters (12 tools)

Tool	Description
`get_promoters`	List promoters with 26 filter/sort/search params
`get_promoter`	Get single promoter by ID or lookup (email, auth_token, ref_token, promo_code)
`create_promoter`	Create a new promoter (21 params)
`update_promoter`	Update promoter info (24 params, find_by support)
`accept_promoters`	Accept pending promoters into a campaign (batch)
`reject_promoters`	Reject promoters from a campaign (batch)
`block_promoters`	Block promoters from a campaign (batch)
`archive_promoters`	Archive promoters globally (batch)
`restore_promoters`	Restore archived promoters (batch)
`move_promoters_to_campaign`	Move promoters between campaigns (batch)
`add_promoters_to_campaign`	Add promoters to a campaign (batch)
`assign_parent_promoter`	Set parent promoter for sub-affiliate relationship (batch)

Referrals (5 tools)

Tool	Description
`get_referrals`	List referrals with filters (type, promoter_id, state, search)
`get_referral`	Get single referral by ID or lookup (email, uid, username)
`update_referral`	Update referral (email, uid, username, promoter_campaign_id, split_details)
`move_referrals_to_promoter`	Move referrals to a different promoter (batch)
`delete_referrals`	Delete referrals (batch)

Commissions (7 tools)

Tool	Description
`get_commissions`	List commissions with filters (status, paid, fulfilled, sale_amount, campaign_id, fraud_check)
`create_commission`	Create a commission (sale type or custom type)
`update_commission`	Update commission notes (internal_note, external_note)
`approve_commissions`	Approve commissions (batch)
`deny_commissions`	Deny commissions (batch)
`mark_commissions_fulfilled`	Mark non-monetary commissions as fulfilled (batch)
`mark_commissions_unfulfilled`	Mark non-monetary commissions as unfulfilled (batch)

Payouts (4 tools)

Tool	Description
`get_payouts`	List payouts with 18 filter params (status, campaign, dates, method, promoter)
`get_payouts_grouped_by_promoters`	Payouts aggregated by promoter
`get_payout_stats`	Payout statistics with breakdowns (stats_by)
`get_due_payout_stats`	Due payout statistics

Reports (5 tools)

Tool	Description
`get_reports_campaigns`	Campaign performance reports (19 available columns, time-period breakdowns)
`get_reports_overview`	Overview time-series reports
`get_reports_promoters`	Promoter performance reports
`get_reports_traffic_sources`	Traffic source reports (11 columns)
`get_reports_urls`	URL performance reports (12 columns)

Tool	Description
`get_promo_codes`	List promo codes (optional filter by promoter_campaign_id)
`get_promo_code`	Get single promo code by ID
`create_promo_code`	Create a promo code (Stripe only — requires code, reward_id, promoter_campaign_id)
`update_promo_code`	Update promo code
`archive_promo_code`	Archive (soft-delete) a promo code

Promoter Campaigns (2 tools)

Tool	Description
`get_promoter_campaigns`	List all promoter-campaign links with stats
`update_promoter_campaign`	Update promoter campaign (ref_token, state, coupon, rewards, customization)

Batch Processes (3 tools)

Tool	Description
`get_batch_processes`	List batch processes with optional status filter
`get_batch_process`	Get details of a specific batch process by ID
`get_batch_progress`	Quick progress overview — map of batch IDs to completion percentage

All batch operations run asynchronously when more than 5 IDs are provided. Monetary amounts are in cents (divide by 100 for dollars).

Project Structure

firstpromoter-mcp/
├── src/
│   ├── index.ts              # Entry point: server creation + stdio transport
│   ├── api.ts                # API helper (auth, fetch, errors, rate limiting, retry)
│   ├── logger.ts             # Stderr logger (debug/info/warn/error, LOG_LEVEL)
│   ├── formatters.ts         # Response formatters (structured text + raw JSON)
│   └── tools/
│       ├── index.ts              # Tool registry — registers all 43 tools
│       ├── promoters.ts          # 12 promoter tools
│       ├── referrals.ts          # 5 referral tools
│       ├── commissions.ts        # 7 commission tools
│       ├── payouts.ts            # 4 payout tools
│       ├── reports.ts            # 5 report tools
│       ├── promo-codes.ts        # 5 promo code tools
│       ├── promoter-campaigns.ts # 2 promoter campaign tools
│       └── batch-processes.ts    # 3 batch process tools
├── dist/                  # Compiled JavaScript
├── Dockerfile             # Multi-stage Docker build
├── package.json
├── tsconfig.json
└── .env.example

Configuration

Variable	Default	Description
`FP_BEARER_TOKEN`	—	FirstPromoter API token (required)
`FP_ACCOUNT_ID`	—	FirstPromoter account ID (required)
`LOG_LEVEL`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`

Set LOG_LEVEL=debug to see every API request/response with timing. Logs go to stderr only (stdout is reserved for MCP protocol).

Development Scripts

Command	Description
`npm run dev:stdio`	Run server in development mode (auto-loads .env)
`npm run build`	Compile TypeScript to JavaScript
`npm start`	Run compiled server (auto-loads .env)
`docker build -t firstpromoter-mcp .`	Build Docker image

Roadmap

Phase 1: Local stdio server with all promoter tools (12 tools)
Phase 2: All remaining API tools — referrals, commissions, payouts, reports, promo codes, promoter campaigns, batch processes (31 tools)
Phase 3: Production polish (error handling, logging, rate limiting)

A remote HTTP server with OAuth authentication will be developed as a separate project.

Troubleshooting

"Credentials not configured" error

Make sure your .env file (local dev) or Claude Desktop config env section contains valid FP_BEARER_TOKEN and FP_ACCOUNT_ID.

Server doesn't appear in Claude Desktop

Check Claude Desktop logs for errors
Verify the Docker image built successfully: docker images | grep firstpromoter
Restart Claude Desktop after config changes

API errors from FirstPromoter

401 Unauthorized — check your Bearer token and Account-ID
404 invalid_route — verify Account-ID is correct (not a token)
429 Too Many Requests — rate limit is 400 requests/minute

License

MIT

FirstPromoter MCP Server

FirstPromoter MCP Server (Local)

What is This?

Quick Start

Prerequisites

Step 1: Install Dependencies

Step 2: Configure Credentials

Step 3: Build & Test

Step 4: Connect to Claude Desktop

Option A: Docker (recommended)

Option B: Direct Node.js

Step 5: Try It Out

Available Tools (43 total)

Promoters (12 tools)

Referrals (5 tools)

Commissions (7 tools)

Payouts (4 tools)

Reports (5 tools)

Promoter Campaigns (2 tools)

Batch Processes (3 tools)

Project Structure

Configuration

Development Scripts

Roadmap

Troubleshooting

"Credentials not configured" error

Server doesn't appear in Claude Desktop

API errors from FirstPromoter

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

FirstPromoter MCP Server (Local)

What is This?

Quick Start

Prerequisites

Step 1: Install Dependencies

Step 2: Configure Credentials

Step 3: Build & Test

Step 4: Connect to Claude Desktop

Option A: Docker (recommended)

Option B: Direct Node.js

Step 5: Try It Out

Available Tools (43 total)

Promoters (12 tools)

Referrals (5 tools)

Commissions (7 tools)

Payouts (4 tools)

Reports (5 tools)

Promo Codes (5 tools)

Promoter Campaigns (2 tools)

Batch Processes (3 tools)

Project Structure

Configuration

Development Scripts

Roadmap

Troubleshooting

"Credentials not configured" error

Server doesn't appear in Claude Desktop

API errors from FirstPromoter

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API