FirstPromoter MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the FirstPromoter affiliate management platform. Designed for remote multi-user deployment using HTTP/SSE transport.

🎯 Features

Referral Management

• get_referrals - List all referrals with search, state, and promoter filters
• get_referral - Get detailed information about a specific referral

Promoter Management

• get_promoters - List all promoters with filters
• create_promoter - Create a new promoter
• get_promoter - Get detailed promoter information
• update_promoter - Update promoter details
• add_promoters_to_campaign - Add promoters to a campaign
• move_promoters_to_campaign - Move promoters between campaigns
• accept_promoters - Accept pending promoters
• reject_promoters - Reject pending promoters
• block_promoters - Block promoters
• archive_promoters - Archive promoters
• restore_promoters - Restore archived promoters

Campaign Management

• get_promoter_campaigns - List promoter-campaign relationships
• update_promoter_campaign - Update campaign settings

Commission Management

• get_commissions - List all commissions with filters
• approve_commissions - Approve pending commissions
• deny_commissions - Deny commissions

Payout Management

• get_payouts - List all payouts
• get_payout_stats - Get payout statistics
• get_due_payout_stats - Get due payout statistics
• get_payouts_by_promoter - Get payouts grouped by promoter

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │     │   Claude Code   │     │       n8n       │
│    (Client)     │     │    (Client)     │     │    (Client)     │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │    HTTP/SSE           │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   Hetzner CPX22 Server  │
                    │   (Dokploy/Docker)      │
                    │                         │
                    │  ┌───────────────────┐  │
                    │  │ FirstPromoter MCP │  │
                    │  │      Server       │  │
                    │  │    (Port 8000)    │  │
                    │  └─────────┬─────────┘  │
                    └────────────┼────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   FirstPromoter API     │
                    │ api.firstpromoter.com   │
                    └─────────────────────────┘

🚀 Deployment to Dokploy

Prerequisites

• Dokploy v0.26.6+ installed on your Hetzner server
• FirstPromoter API Key and Account ID
• (Optional) Domain name for HTTPS

Step 1: Create the Project in Dokploy

1. Log into your Dokploy dashboard
2. Click "Create Project"
3. Name it firstpromoter-mcp

Step 2: Create the Application

1. Inside the project, click "Create Application"
2. Select "Docker Compose" as the source type
3. Choose "Git" or "Upload" based on your preference

Option A: Git Repository

• Push this code to a Git repository
• Connect the repository in Dokploy

Option B: Direct Upload

• Upload all files to Dokploy

Step 3: Configure Environment Variables

In Dokploy's application settings, add these environment variables:

Step 4: Configure Domain (HTTPS)

1. In Dokploy, go to Domains
2. Add your domain (e.g., mcp.yourdomain.com)
3. Enable HTTPS (Let's Encrypt)
4. Set the target port to 8000

Step 5: Deploy

Click Deploy in Dokploy. The server will build and start.

🔌 Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "firstpromoter": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.yourdomain.com/sse"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add firstpromoter --transport sse --url "https://mcp.yourdomain.com/sse"

n8n Integration

Option 1: Using MCP Node (if available)

Configure the MCP node with:

• Transport: SSE
• URL: https://mcp.yourdomain.com/sse

Option 2: Direct HTTP Requests

Use the HTTP Request node to call FirstPromoter API directly. The MCP server exposes the same endpoints.

🔐 Security Recommendations

1. Enable HTTPS

Always use HTTPS in production. Dokploy handles this automatically with Let's Encrypt.

2. IP Allowlisting

In Dokploy, you can configure firewall rules to only allow specific IPs:

• Your office IP
• Your colleagues' IPs
• n8n server IP

3. Authentication Token

Set MCP_AUTH_TOKEN to require clients to authenticate. Clients must include this token in their requests.

4. Rate Limiting

FirstPromoter has a rate limit of 400 requests/minute. The MCP server doesn't add additional rate limiting, but you can add a reverse proxy (like Nginx) in front if needed.

🧪 Testing

Health Check

curl https://mcp.yourdomain.com/health

List Tools

curl https://mcp.yourdomain.com/sse \
  -H "Accept: text/event-stream"

Local Testing (Docker)

# Build
docker build -t firstpromoter-mcp .

# Run
docker run -d \
  -e FP_API_KEY=your_key \
  -e FP_ACCOUNT_ID=your_account_id \
  -p 8000:8000 \
  firstpromoter-mcp

# Test
curl http://localhost:8000/health

📝 Example Usage

Once connected, you can ask Claude:

Promoter Management:

• "Show me all pending promoters"
• "Create a new promoter with email john@example.com"
• "Accept promoter ID 12345"
• "Move promoters 100, 101, 102 to campaign 5"

Commission Management:

• "List all pending commissions"
• "Approve commission IDs 500, 501, 502"
• "Show commission stats"

Payout Management:

• "What are the payout statistics?"
• "Show me all pending payouts"
• "Get due payout stats"

Referral Management:

• "List all referrals from promoter 123"
• "Get details for referral ID 456"

🔧 Troubleshooting

Server won't start

Check logs in Dokploy or run:

docker logs firstpromoter-mcp

Common issues:

• Missing FP_API_KEY or FP_ACCOUNT_ID
• Port 8000 already in use

API errors

Verify your FirstPromoter credentials:

1. Log into FirstPromoter
2. Go to Settings → Integrations → Manage API Keys
3. Ensure the API key has appropriate permissions

Connection refused

• Check if the container is running
• Verify Dokploy domain configuration
• Check firewall rules

📄 License

MIT License

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

📚 Resources

• FirstPromoter API Documentation
• MCP Protocol Specification
• Dokploy Documentation