Joy Loyalty MCP Server

MCP (Model Context Protocol) server for Joy Loyalty REST API v2. Enables AI assistants to manage customers, points, rewards, VIP tiers, programs, and referrals.

Quick Start

npx joy-loyalty-mcp-server

Prerequisites

• Node.js >= 18
• Joy Loyalty app installed on Shopify store (Advanced or Enterprise plan)
• API credentials from: Shopify Admin > Apps > Joy Loyalty > Settings > Advanced > REST API

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | JOY_APP_KEY | Yes | Joy Loyalty API app key | | JOY_SECRET_KEY | Yes | Joy Loyalty API secret key | | JOY_API_BASE_URL | No | API base URL (default: https://api.joy.so) |

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "joy-loyalty": {
      "command": "npx",
      "args": ["-y", "joy-loyalty-mcp-server"],
      "env": {
        "JOY_APP_KEY": "your_app_key",
        "JOY_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add joy-loyalty -e JOY_APP_KEY=xxx -e JOY_SECRET_KEY=yyy -- npx -y joy-loyalty-mcp-server

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "joy-loyalty": {
      "command": "npx",
      "args": ["-y", "joy-loyalty-mcp-server"],
      "env": {
        "JOY_APP_KEY": "your_app_key",
        "JOY_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Windsurf / Cline / Other MCP Clients

Same pattern — set command: "npx", args: ["-y", "joy-loyalty-mcp-server"], and provide env vars.

Available Tools (19)

Shop

| Tool | Description | |------|-------------| | joy_whoami | Get authenticated shop info, verify API connection |

Customers

| Tool | Description | |------|-------------| | joy_list_customers | List customers with pagination and date filters | | joy_get_customer | Get customer by Shopify ID or Joy ID | | joy_update_customer_tier | Move customer to a different VIP tier |

Point Transactions

| Tool | Description | |------|-------------| | joy_list_transactions | List point transactions for a customer | | joy_award_points | Award points to a customer | | joy_deduct_points | Deduct points from a customer | | joy_adjust_points | Adjust points (positive or negative) | | joy_reset_points | Reset customer points to zero |

Programs

| Tool | Description | |------|-------------| | joy_list_programs | List earning programs, optionally by customer eligibility | | joy_calculate_points | Calculate points for a program and order | | joy_redeem | Redeem a reward for a customer |

Rewards

| Tool | Description | |------|-------------| | joy_list_rewards | List rewards/coupons for a customer | | joy_refund_coupon | Refund an unused coupon, return points |

VIP Tiers

| Tool | Description | |------|-------------| | joy_list_tiers | List all VIP tiers with requirements | | joy_get_tier | Get tier details by ID | | joy_get_tier_benefits | Get tier benefits by type |

Referrals

| Tool | Description | |------|-------------| | joy_create_referral_invite | Generate referral invite link | | joy_get_referral_summary | Get customer's referral stats | | joy_referral_analytics | Get referral program analytics |

Example Prompts

Once connected, you can ask your AI assistant:

• "Check if the Joy API is connected"
• "Show me the first 20 loyalty customers"
• "Look up customer with Shopify ID 7891234567890"
• "Award 100 points to customer 789 for completing a survey"
• "What VIP tiers are available?"
• "Show point history for customer 789"
• "What earning programs are active?"
• "Generate a referral link for customer abc123"

API Details

• Base URL: https://api.joy.so/rest_api/v2
• Auth: Header-based (X-Joy-Loyalty-App-Key, X-Joy-Loyalty-Secret-Key) — no JWT required
• Rate Limit: 120 requests per 10 seconds
• Pagination: Cursor-based (use after/before with document IDs)
• Plan Required: Advanced or Enterprise

Note: The API uses point (singular) for all point-related fields, not points.

Development

git clone <repo-url>
cd joy-mcp-server
npm install
npm run build
npm start

License

MIT