Open Loyalty MCP Server

MCP (Model Context Protocol) server for interacting with Open Loyalty API. This server enables AI agents like Claude and ChatGPT to manage loyalty programs, members, points, rewards, and transactions.

Prerequisites

• Node.js 18 or later
• An Open Loyalty account with API access

Installation

Via npm (Recommended)

npm install -g @open-loyalty/mcp-server

Or use directly with npx (no installation required):

npx @open-loyalty/mcp-server

From Source

git clone https://github.com/OpenLoyalty/openloyalty-mcp.git
cd openloyalty-mcp/openloyalty-mcp
npm install
npm run build

Configuration

The server requires the following environment variables:

| Variable | Description | |----------|-------------| | OPENLOYALTY_API_URL | Your Open Loyalty API URL (e.g., https://api.openloyalty.io) | | OPENLOYALTY_API_TOKEN | Your API authentication token | | OPENLOYALTY_DEFAULT_STORE_CODE | Default store code (e.g., default) |

For local development, create a .env file based on .env.example:

cp .env.example .env

Transport Modes

The server supports two transport modes for different use cases:

| Mode | Binary | Use Case | |------|--------|----------| | stdio | openloyalty-mcp | Local usage with Claude Desktop, Claude Code, Cursor | | HTTP | openloyalty-mcp-http | Remote hosting, ChatGPT Actions, web integrations |

Both modes provide identical functionality - only the transport layer differs.

Stdio Mode (Local)

Use stdio mode when running the server locally with MCP clients like Claude Desktop.

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

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

Using npx (Recommended)

{
  "mcpServers": {
    "openloyalty": {
      "command": "npx",
      "args": ["-y", "@open-loyalty/mcp-server"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "openloyalty": {
      "command": "openloyalty-mcp",
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "openloyalty": {
      "command": "node",
      "args": ["/path/to/openloyalty-mcp/dist/index.js"],
      "env": {
        "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
        "OPENLOYALTY_API_TOKEN": "your-api-token",
        "OPENLOYALTY_DEFAULT_STORE_CODE": "default"
      }
    }
  }
}

HTTP Mode (Remote Hosting)

Use HTTP mode when hosting the server remotely for web-based MCP clients or ChatGPT Actions.

Running HTTP Server

# Using the binary
openloyalty-mcp-http

# Using npm scripts
npm run start:http

# Development mode
npm run dev:http

HTTP Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENLOYALTY_API_URL | Yes* | Open Loyalty API URL | | OPENLOYALTY_API_TOKEN | Yes* | API authentication token | | OPENLOYALTY_DEFAULT_STORE_CODE | Yes* | Default store code | | PORT or MCP_HTTP_PORT | No | Server port (default: 3000) | | OAUTH_ENABLED | No | Enable multi-tenant OAuth mode | | BASE_URL | OAuth | Public URL for OAuth callbacks | | REDIS_URL | OAuth | Redis URL for token storage |

*Required when OAUTH_ENABLED is not set or false

HTTP Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | Server info | | /health | GET | Health check | | /mcp | POST | MCP message endpoint | | /mcp | GET | SSE stream (with session) | | /mcp | DELETE | Close session |

Single-Tenant Mode

For dedicated deployments with fixed credentials:

export OPENLOYALTY_API_URL="https://api.openloyalty.io"
export OPENLOYALTY_API_TOKEN="your-token"
export OPENLOYALTY_DEFAULT_STORE_CODE="default"
openloyalty-mcp-http

Multi-Tenant OAuth Mode

For shared deployments where each user provides their own credentials:

export OAUTH_ENABLED=true
export BASE_URL="https://your-server.com"
export REDIS_URL="redis://localhost:6379"
openloyalty-mcp-http

With OAuth enabled, additional endpoints are available:

| Endpoint | Description | |----------|-------------| | /authorize | OAuth authorization form | | /token | Token exchange | | /register | Dynamic client registration | | /.well-known/oauth-authorization-server | OAuth metadata |

ChatGPT Actions Integration

To use with ChatGPT:

1. Host the HTTP server with OAuth enabled
2. In GPT Editor → Configure → Actions:
   • Authentication: OAuth
   • Authorization URL: https://your-server.com/authorize
   • Token URL: https://your-server.com/token
   • Scope: mcp
3. Add your MCP endpoint: https://your-server.com/mcp

Users will be prompted to enter their Open Loyalty credentials during the OAuth flow.

Development

# Run stdio server in development mode
npm run dev

# Run HTTP server in development mode
npm run dev:http

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

Available Tools (112 total)

Wallet Types (2 tools)

• openloyalty_wallet_type_list - List all wallet types (point currencies)
• openloyalty_wallet_type_get - Get details for a specific wallet type

Tier Sets (6 tools)

• openloyalty_tierset_list - List all tier sets
• openloyalty_tierset_create - Create a new tier set
• openloyalty_tierset_get - Get tier set details with condition IDs
• openloyalty_tierset_update - Update tier set metadata
• openloyalty_tierset_update_tiers - Define tier thresholds
• openloyalty_tierset_get_tiers - Get all tiers in a tier set

Members (10 tools)

• openloyalty_member_create - Register a new loyalty program member
• openloyalty_member_get - Get member details including profile, points balance, and tier status
• openloyalty_member_list - Search and list members with optional filters
• openloyalty_member_update - Update member profile fields
• openloyalty_member_activate - Activate a deactivated member
• openloyalty_member_deactivate - Deactivate an active member
• openloyalty_member_delete - Permanently remove member (GDPR compliance)
• openloyalty_member_get_tier_progress - Get tier progression status
• openloyalty_member_assign_tier - Manually assign tier to member
• openloyalty_member_remove_manual_tier - Remove manual tier assignment

Points (6 tools)

• openloyalty_points_add - Add points to member wallet (with optional expiration/lock)
• openloyalty_points_spend - Deduct points from member wallet
• openloyalty_points_transfer - Transfer points between members (P2P)
• openloyalty_points_get_balance - Get member points balance breakdown
• openloyalty_points_get_history - Get points transaction history
• openloyalty_points_get_histogram - Get points histogram for visualization

Rewards (9 tools)

• openloyalty_reward_list - List available rewards
• openloyalty_reward_create - Create a new reward
• openloyalty_reward_get - Get reward details
• openloyalty_reward_update - Update reward configuration
• openloyalty_reward_activate - Activate a reward
• openloyalty_reward_deactivate - Deactivate a reward
• openloyalty_reward_buy - Purchase reward for member (deducts points)
• openloyalty_reward_redeem - Mark coupon as used
• openloyalty_reward_category_list - List reward categories

Transactions (4 tools)

• openloyalty_transaction_create - Record a purchase transaction
• openloyalty_transaction_get - Get transaction details
• openloyalty_transaction_list - List transactions with filters
• openloyalty_transaction_assign_member - Assign unmatched transaction to member

Campaigns (12 tools)

• openloyalty_campaign_list - List all campaigns with optional filters
• openloyalty_campaign_create - Create campaign to automate engagement
• openloyalty_campaign_get - Get full campaign configuration
• openloyalty_campaign_update - Update campaign (full replacement)
• openloyalty_campaign_patch - Patch campaign (active/displayOrder only)
• openloyalty_campaign_delete - Permanently delete a campaign
• openloyalty_campaign_simulate - Preview campaign effects without executing
• openloyalty_campaign_generate_codes - Generate redemption codes
• openloyalty_campaign_list_codes - List redemption codes
• openloyalty_campaign_get_available - Get campaigns available for member
• openloyalty_campaign_get_visible - Get campaigns visible to member
• openloyalty_campaign_get_leaderboard - Get campaign leaderboard

Segments (9 tools)

• openloyalty_segment_list - List customer segments
• openloyalty_segment_create - Create segment to group members
• openloyalty_segment_get - Get segment details with criteria
• openloyalty_segment_update - Update segment configuration
• openloyalty_segment_delete - Permanently delete a segment
• openloyalty_segment_get_members - Get members matching segment
• openloyalty_segment_activate - Activate a segment
• openloyalty_segment_deactivate - Deactivate a segment
• openloyalty_segment_get_resources - Get resources associated with segment

Achievements (7 tools)

• openloyalty_achievement_list - List achievements
• openloyalty_achievement_create - Create achievement for gamification
• openloyalty_achievement_get - Get achievement details
• openloyalty_achievement_update - Update achievement (full replacement)
• openloyalty_achievement_patch - Patch achievement (active/displayOrder)
• openloyalty_achievement_get_member_progress - Get member's progress on achievement
• openloyalty_achievement_list_member_achievements - List member's achievements

Badges (4 tools)

• openloyalty_badge_list - List badge types
• openloyalty_badge_get - Get badge type details
• openloyalty_badge_update - Update badge type configuration
• openloyalty_badge_get_member_badges - Get badges earned by member

Analytics (9 tools)

• openloyalty_analytics_tiers - Get tier distribution with member counts
• openloyalty_analytics_members - Get member statistics (new, active, inactive)
• openloyalty_analytics_points - Get points statistics (issued, spent, expired)
• openloyalty_analytics_transactions - Get transaction statistics
• openloyalty_analytics_referrals - Get referral program statistics
• openloyalty_analytics_campaigns - Get campaign performance metrics
• openloyalty_analytics_dashboard - Get dashboard overview metrics
• openloyalty_analytics_units - Get wallet-specific metrics
• openloyalty_analytics_campaign_detail - Get detailed campaign analytics

Admin Users (6 tools)

• openloyalty_admin_list - List admin users
• openloyalty_admin_create - Create admin user
• openloyalty_admin_get - Get admin user details
• openloyalty_admin_update - Update admin user profile
• openloyalty_admin_change_password - Change admin password
• openloyalty_admin_get_permissions - Get admin permissions

Roles/ACL (6 tools)

• openloyalty_role_list - List roles
• openloyalty_role_create - Create role with permissions
• openloyalty_role_get - Get role details
• openloyalty_role_update - Update role
• openloyalty_role_delete - Delete role
• openloyalty_acl_get_resources - Get available ACL resources and actions

API Keys (3 tools)

• openloyalty_apikey_create - Create API key (token shown once!)
• openloyalty_apikey_list - List API keys for admin
• openloyalty_apikey_delete - Delete API key

Audit Logs (2 tools)

• openloyalty_audit_list - List audit log entries
• openloyalty_audit_export - Export audit logs

Stores (4 tools)

• openloyalty_store_list - List stores
• openloyalty_store_create - Create store for multi-tenancy
• openloyalty_store_get - Get store details
• openloyalty_store_update - Update store configuration

Webhooks (6 tools)

• openloyalty_webhook_list - List webhook subscriptions
• openloyalty_webhook_create - Create webhook subscription for event notifications
• openloyalty_webhook_get - Get webhook subscription details
• openloyalty_webhook_update - Update webhook subscription
• openloyalty_webhook_delete - Delete webhook subscription
• openloyalty_webhook_events - List available webhook event types

Import (3 tools)

• openloyalty_import_create - Create bulk import from CSV
• openloyalty_import_list - List imports with status
• openloyalty_import_get - Get import details and item statuses

Export (4 tools)

• openloyalty_export_create - Create data export (async)
• openloyalty_export_list - List exports with status
• openloyalty_export_get - Get export status and details
• openloyalty_export_download - Download export CSV (when status='done')

Example Workflows

1. Create 3-Tier Loyalty Program

openloyalty_wallet_type_list
openloyalty_tierset_create({ name: "VIP Program", conditions: [{ attribute: "activeUnits", walletType: "points" }] })
openloyalty_tierset_get({ tierSetId: "..." })
openloyalty_tierset_update_tiers({
  tierSetId: "...",
  tiers: [
    { name: "Bronze", conditions: [{ conditionId: "xxx", value: 400 }] },
    { name: "Silver", conditions: [{ conditionId: "xxx", value: 800 }] },
    { name: "Gold", conditions: [{ conditionId: "xxx", value: 1200 }] }
  ]
})

2. Full Member Lifecycle

// Register member
openloyalty_member_create({ email: "[email protected]", firstName: "John", lastName: "Doe" })

// Add welcome bonus
openloyalty_points_add({ memberId: "...", points: 100, comment: "Welcome bonus" })

// Record purchase (auto-earns points via campaigns)
openloyalty_transaction_create({
  header: { documentNumber: "INV-001", purchasedAt: "2024-01-15T10:00:00Z" },
  items: [{ sku: "PROD-1", name: "Widget", grossValue: 99.99, category: "Electronics" }],
  customerData: { email: "[email protected]" }
})

// Check tier progress
openloyalty_member_get_tier_progress({ memberId: "..." })

3. Reward Redemption Flow

// List available rewards
openloyalty_reward_list({ active: true })

// Check member balance
openloyalty_points_get_balance({ memberId: "..." })

// Purchase reward (deducts points, returns coupon code)
openloyalty_reward_buy({ rewardId: "...", memberId: "..." })

// Later: mark coupon as used
openloyalty_reward_redeem({ memberId: "...", couponCode: "COUP-ABC123" })

4. Assign Unmatched Transaction

// Find unmatched transactions
openloyalty_transaction_list({ matched: false })

// Assign to member (triggers point campaigns)
openloyalty_transaction_assign_member({ documentNumber: "INV-999", loyaltyCardNumber: "CARD-123" })

5. Create Double Points Campaign for Gold Tier

// First, find the Gold tier level ID
openloyalty_tierset_get_tiers({ tierSetId: "..." })

// Create a segment targeting Gold tier members
openloyalty_segment_create({
  name: "Gold Members",
  parts: [{
    criteria: [{
      type: "tier",
      tierIds: ["gold-level-id"]
    }]
  }]
})

// Create campaign with double points effect
openloyalty_campaign_create({
  type: "direct",
  trigger: "transaction",
  translations: { en: { name: "Double Points for Gold", description: "Gold members earn 2x points" } },
  activity: { startsAt: "2024-01-01T00:00:00Z" },
  rules: [{
    name: "Double points",
    effects: [{
      effect: "give_points",
      pointsRule: { multiplier: 2 }
    }]
  }],
  audience: {
    target: "segment",
    segments: ["segment-id"]
  },
  active: true
})

// Test the campaign before it triggers
openloyalty_campaign_simulate({
  trigger: "transaction",
  transaction: { grossValue: 100 },
  customer: { email: "[email protected]" }
})

6. Create VIP Segment Based on Transaction Count

// Create segment for members with 10+ transactions
openloyalty_segment_create({
  name: "VIP Customers",
  description: "Members with 10 or more purchases",
  parts: [{
    criteria: [{
      type: "transaction_count",
      min: 10
    }]
  }],
  active: true
})

// Check segment membership
openloyalty_segment_get_members({ segmentId: "..." })

// Use for campaign targeting
openloyalty_campaign_create({
  type: "direct",
  trigger: "transaction",
  translations: { en: { name: "VIP Bonus" } },
  activity: { startsAt: "2024-01-01T00:00:00Z" },
  rules: [{
    name: "VIP Bonus Points",
    effects: [{ effect: "give_points", pointsRule: { value: 50 } }]
  }],
  audience: { target: "segment", segments: ["vip-segment-id"] },
  active: true
})

7. Create Purchase Achievement with Badge

// Create an achievement for making 5 purchases
openloyalty_achievement_create({
  translations: { en: { name: "Frequent Shopper", description: "Make 5 purchases" } },
  rules: [{
    trigger: "transaction",
    completeRule: {
      periodGoal: 5,
      period: { type: "forever" }
    }
  }],
  badgeTypeId: "shopper-badge-id",
  active: true
})

// Check member progress
openloyalty_achievement_get_member_progress({ memberId: "...", achievementId: "..." })

// List all member achievements and badges
openloyalty_achievement_list_member_achievements({ memberId: "..." })
openloyalty_badge_get_member_badges({ memberId: "..." })

8. Segment Logic: OR vs AND

// Parts use OR logic - member matches if ANY part matches
// Criteria within parts use AND logic - must match ALL criteria in that part

// Example: (Gold tier AND 1000+ points) OR (10+ transactions)
openloyalty_segment_create({
  name: "High Value Members",
  parts: [
    {
      // Part 1: Gold tier with high balance
      criteria: [
        { type: "tier", tierIds: ["gold-level-id"] },
        { type: "points_balance", min: 1000 }
      ]
    },
    {
      // Part 2: Frequent shoppers (OR with Part 1)
      criteria: [
        { type: "transaction_count", min: 10 }
      ]
    }
  ]
})

9. Create Read-Only Analyst Role

// Discover available ACL resources and actions
openloyalty_acl_get_resources()

// Create a role with VIEW-only permissions
openloyalty_role_create({
  name: "Analyst",
  permissions: [
    { resource: "ANALYTICS", access: "VIEW" },
    { resource: "MEMBER", access: "VIEW" },
    { resource: "TRANSACTION", access: "VIEW" },
    { resource: "CAMPAIGN", access: "VIEW" }
  ]
})

// Create admin with analyst role
openloyalty_admin_create({
  email: "[email protected]",
  password: "SecurePass123!",
  firstName: "Data",
  lastName: "Analyst",
  roles: ["analyst-role-id"]
})

10. Generate API Key for Integration

// Get admin to create API key for
openloyalty_admin_list({ email: "[email protected]" })

// Create API key - CRITICAL: Save the token immediately!
openloyalty_apikey_create({
  adminId: "admin-uuid",
  name: "CRM Integration Key",
  expirationDate: "2025-12-31"
})
// Response includes token that is ONLY shown once

// List API keys (tokens not shown)
openloyalty_apikey_list({ adminId: "admin-uuid" })

11. Analyze Program Performance

// Get high-level dashboard metrics
openloyalty_analytics_dashboard()

// Analyze tier distribution
openloyalty_analytics_tiers({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Check points economy
openloyalty_analytics_points({ dateFrom: "2024-01-01", dateTo: "2024-12-31" })

// Analyze specific campaign
openloyalty_analytics_campaign_detail({ campaignId: "campaign-uuid" })

// Get wallet-specific metrics
openloyalty_analytics_units({ walletTypeCode: "points" })

12. Audit User Actions

// List recent audit entries
openloyalty_audit_list({ perPage: 50 })

// Filter by specific user
openloyalty_audit_list({ username: "[email protected]" })

// Filter by entity type and date range
openloyalty_audit_list({
  entityType: "MEMBER",
  dateFrom: "2024-01-01",
  dateTo: "2024-01-31"
})

// Export audit logs for compliance
openloyalty_audit_export({
  dateFrom: "2024-01-01",
  dateTo: "2024-12-31"
})

13. Multi-Tenant Store Setup

// Create a new store for a region
openloyalty_store_create({
  code: "EU",
  name: "European Store",
  currency: "EUR",
  active: true
})

// List all stores
openloyalty_store_list()

// Use storeCode in subsequent operations
openloyalty_member_create({
  email: "[email protected]",
  firstName: "Jean",
  lastName: "Dupont",
  storeCode: "EU"
})

14. Subscribe to Member Events for CRM Sync

// Discover available event types
openloyalty_webhook_events()

// Subscribe to member creation events
openloyalty_webhook_create({
  eventName: "member.created",
  url: "https://crm.example.com/webhooks/loyalty",
  headers: [
    { headerName: "Authorization", headerValue: "Bearer crm-token" }
  ]
})

// List current subscriptions
openloyalty_webhook_list()

// Update subscription URL
openloyalty_webhook_update({
  webhookSubscriptionId: "...",
  url: "https://crm-v2.example.com/webhooks/loyalty"
})

15. Bulk Import Members from CSV

// Create import with CSV content
openloyalty_import_create({
  type: "member",
  fileContent: "email,firstName,lastName\[email protected],John,Doe\[email protected],Jane,Smith",
  fileName: "members.csv"
})

// Poll import status
openloyalty_import_list({ type: "member" })

// Check individual item statuses
openloyalty_import_get({ importId: "..." })

16. Export Campaign Codes and Download

// Create export for campaign codes
openloyalty_export_create({
  type: "campaignCode",
  filters: { campaignId: "campaign-uuid" }
})

// Poll until status is 'done'
openloyalty_export_get({ exportId: "..." })

// Download the CSV file
openloyalty_export_download({ exportId: "..." })

17. Bulk Add Points via Import

// Create import for adding points to multiple members
openloyalty_import_create({
  type: "unitTransferAdding",
  fileContent: "loyaltyCardNumber,points,comment\nCARD-001,500,Promotion bonus\nCARD-002,500,Promotion bonus"
})

// Check import progress
openloyalty_import_get({ importId: "..." })

Links

• GitHub: OpenLoyalty/openloyalty-mcp
• Open Loyalty: openloyalty.io
• MCP Protocol: modelcontextprotocol.io

License

MIT