抽奖管理 MCP 服务器

 ___
/ __|_ __ _____ ___ _ __ _ __  ___ __ _
\__ \ V  V / -_) -_) '_ \ '_ \/ -_) _` |
|___/\_/\_/\___\___| .__/ .__/\___\__,_|
                   |_|  |_|

Sweeppea MCP Server

Model Context Protocol for Sweepstakes Management

How It Works

The Sweeppea MCP Server is a secure bridge between AI assistants and the Sweeppea API. It translates natural language interactions into structured API calls, giving your AI assistant full access to sweepstakes management — participants, official rules, winners, calendars, billing, and more.

Your AI Assistant  →  MCP (Model Context Protocol)  →  Sweeppea MCP Server  →  Sweeppea API v3

No local setup required — just point your MCP client to the endpoint and authenticate.

Authentication & Pricing

This MCP server requires a Sweeppea API Key tied to an active subscription.

Running sweepstakes in the United States and/or Canada is legally complex. Each state has its own regulations — registration requirements, bonding thresholds, void-where-prohibited rules, prize disclosure laws, and official rules that must comply with federal and state-level consumer protection statutes. Getting any of this wrong exposes sponsors to real legal liability.

Sweeppea handles that complexity for you and much more. The platform generates legally compliant official rules, manages multi-state eligibility, enforces entry limits, and provides an auditable record of every participant and winner draw. The API Key you use to connect isn't just authentication — it's your access to a system built specifically to keep sweepstakes legally defensible.

To get started:

1. Create an account at www.sweeppea.com
2. Choose a plan that fits your needs
3. Get your API Key from the API dashboard
4. Connect your MCP client using the configuration guides below

Documentation:

• MCP Server docs: mcpdocs.sweeppea.com
• API documentation: apidocs.sweeppea.com

Server-side Validations

The server enforces business and legal rules before a tool executes. If a call violates a rule, the tool is rejected and never reaches the Sweeppea API — no resources are created.

Two layers run on every tools/call:

• Hardcoded legal guardrails (inviolable): illegal lottery without AMOE, COPPA (minimum age below 13), alcohol 21+ age gate, nicotine 21+ age gate and state exclusions, no nicotine products as prizes, and explicit confirmation for promotions aimed at minors.
• Dynamic declarative rules (editable by Sweeppea): additional checks on create_sweepstakes, update_entry_settings, create_rules_wizard, create_note, create_ticket, and add_participant.

A rejection returns a structured payload so your AI assistant can recover:

{
  "blocked_by": "server_validation",
  "error_code": "ALCOHOL_AGE_GATE_REQUIRED",
  "error_message": "Alcohol-related sweepstakes require an age gate of 21+.",
  "rule_id": "age_gate_must_be_21_when_active_v1"
}

rule_id is only present for dynamic rules. The AI assistant can read these fields and adjust the arguments before retrying.

Irreversible tools — every delete_*, plus send_message, send_code, cancel_campaign, remove_suppression, unassign_code and remove_drip_contact — require confirm: true and are rejected without it.

Quick Start

Using Claude Code CLI:

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

See Platform Setup for Claude Desktop, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and more.

Available Tools (116)

Account Tools (4)

Entry Page Tools (3)

Sweepstakes Tools (7)

Participant Tools (6)

Group Tools (4)

Notes Tools (5)

Calendar Tools (5)

Rules Tools (5)

Billing & Wallet Tools (4)

Support Tickets Tools (7)

Winners Tools (5)

To-Do Tools (4)

Files Tools (5)

Invoice Tools (5)

Requires the Invoices module enabled on the account — disabled by default. The API returns 403 "module is not enabled" until Sweeppea activates it; contact support to request access.

Survey Tools (7)

Requires the Surveys module enabled on the account — disabled by default. The API returns 403 "module is not enabled" until Sweeppea activates it; contact support to request access.

Codes & Coupons Tools (14)

Writes require the Codes & Coupons module enabled on the account — they return 403 "module not enabled" otherwise. The four reads (fetch_code_stats, fetch_codes, get_code, get_code_settings) do not document that 403; if one of them answers 403, the cause is something else.

Messaging Tools (12)

Writes require the Send Message module enabled on the account — they return 403 "module not enabled" otherwise. The six reads do not document that 403.

Direct sending (send_message, send_code) is a separate switch from the module: an account with the module enabled can still get 403 until Sweeppea support enables direct messages. fetch_messaging_usage reports both, plus plan channels, allowance, sending pauses and 10DLC readiness.

Campaigns cannot be created through the API — they are created in the Sweeppea app. These tools read, pause, resume and cancel them.

Drip Campaigns Tools (7)

Reads require the Drip Marketing module. Writes (pause_drip, resume_drip, remove_drip_contact) require Drip Marketing and Send Message — each missing module returns its own 403. This gate is documented by the API, not yet observed.

Drips are created, edited, activated and deleted only in the Sweeppea app, by design — the API has no endpoints for them. These tools read drips, pause and resume them, and remove a single contact.

Documentation Tools (1)

Utilities Tools (5)

Testing Tools (1)

Usage Examples

Initialize connection:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "client"}
    }
  }'

Add a participant:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "MCP-Session-Id: uuid-xxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "add_participant",
      "arguments": {
        "sweepstakes_token": "xxx-xxx-xxx",
        "email": "user@example.com",
        "fields": {"First_Name": "John", "Last_Name": "Doe"}
      }
    }
  }'

Platform Setup

Claude Code (CLI)

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

Claude Desktop / Cowork

Config file location:

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

Requires Node.js installed.

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header", "Authorization: Bearer YOUR_API_KEY",
        "--header", "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

1. Create or edit the config file with the JSON below
2. Replace YOUR_API_KEY with your Sweeppea API Key
3. Restart Cursor
4. Go to Settings > Tools & MCP
5. Enable the sweeppea server with the toggle switch

{
  "mcpServers": {
    "sweeppea": {
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json (global)

1. Create or edit the config file with the JSON below
2. Replace YOUR_API_KEY with your Sweeppea API Key
3. Go to Settings > Cascade > MCP Servers
4. Verify that sweeppea appears and is enabled

{
  "mcpServers": {
    "sweeppea": {
      "serverUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json (workspace) or User Settings

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sweeppea-api-key",
      "description": "Sweeppea API Key",
      "password": true
    }
  ],
  "servers": {
    "sweeppea": {
      "type": "http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer ${input:sweeppea-api-key}",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json (global) or .gemini/settings.json (project)

{
  "mcpServers": {
    "sweeppea": {
      "httpUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Agent Zero

Open-source AI agent framework with MCP support.

1. Go to Settings > MCP/A2A > MCP Servers
2. Add the JSON configuration below
3. Replace YOUR_API_KEY with your Sweeppea API Key
4. Click Save

{
  "mcpServers": {
    "sweeppea": {
      "description": "Sweeppea - Sweepstakes Management API",
      "type": "streamable-http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Antigravity by Google

~/.gemini/antigravity/mcp_config.json (global)

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY",
        "--header",
        "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Protocol

License

MIT License - see LICENSE file for details.

(c) Sweeppea | All rights reserved