# Sweeppea MCP Server — Full Documentation

> Sweeppea MCP Server is a Model Context Protocol (MCP) server for AI-powered sweepstakes management. It provides 83 tools across 18 categories to manage sweepstakes, participants, official rules, winners, billing, calendar events, support tickets, and more — all accessible through any MCP-compatible AI client via Streamable HTTP transport.

## API Connection

- Endpoint: https://mcp.sweeppea.com/
- Protocol: MCP 2025-11-25 (Streamable HTTP)
- Auth: Bearer token (Sweeppea API key)
- Format: JSON-RPC 2.0

## Quick Start (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"
```

---

## Account Tools (4 tools)

### health_check
Verify connection to Sweeppea API and validate your API key.
- Parameters: none

### get_profile
Get user profile information for a Sweeppea account. Returns user details like name, email, and account settings.
- Parameters: none

### get_business
Get business information for a Sweeppea account. Returns company details, address, and business settings.
- Parameters: none

### get_plan
Get plan details for a Sweeppea subscription. Returns pricing, limits, features, and usage information.
- Parameters: none

---

## Sweepstakes Tools (7 tools)

### fetch_sweepstakes
Get the sweepstakes associated with your account, paginated and summarized. Each item carries a computed lifecycle state (scheduled / running / ended), has_ended and days_until_end — read it before giving operational advice.
- Parameters: page (number, default 1), page_size (number, default 25, max 100), include_settings (boolean, default false — the full Settings object is ~1.5 KB per sweepstakes), include_archived (boolean, default true)
- Response carries pagination.has_more: request the next page or tell the user how many were not listed

### create_sweepstakes
Create a new sweepstakes programmatically.
- Required: sweepstakes_name (string), handler (string, max 20 alphanumeric chars), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), start_time (HH:MM 24h), end_time (HH:MM 24h)
- Guardrail: a name referring to a minor audience (kids, ninos, teens, high school) is rejected unless entrants_are_18_or_older=true — entry pages collect personal data from whoever enters, so the entrant must be an adult
- Optional: sweepstakes_type (number; defaults to 2 Email — recommended; SMS=1 and Social=3 are rarely used and cannot be changed after creation), create_in_calendar (boolean), sync_with_winners (boolean), delete_if_deleted (boolean), delete_if_acct_deleted (boolean)
- Limits: Each account has a per-plan cap on total sweepstakes (no separate active/total distinction — single count). Call `get_plan` to read the account's actual `MaxSweepstakesAllowed`.

### update_sweepstakes
Update an existing sweepstakes. Handler, type, and prize value/description cannot be changed after creation (prize changes go through Sweeppea support).
- Required: sweepstakes_token (UUID)
- Optional: sweepstakes_name (string), start_date, end_date, start_time, end_time

### clone_sweepstakes
Clone an existing sweepstakes with new parameters. Creates a complete copy including entry pages, calendar events, short links, groups, and all configurations.
- Required: handler (original), handler_new (new unique handler), sweepstakes_name, start_date, end_date, start_time, end_time

### pause_sweepstakes
Pause a sweepstakes, setting it to inactive status while preserving all data. Participants will not be able to enter while paused.
- Required: sweepstakes_token (UUID)

### unpause_sweepstakes
Reactivate a paused sweepstakes, allowing participants to enter again.
- Required: sweepstakes_token (UUID)

### delete_sweepstakes
Permanently delete a sweepstakes and all associated data including participants, statistics, and automations.
- Required: sweepstakes_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Participant Tools (6 tools)

### add_participant
Add a new participant to a sweepstakes. Only one participant at a time. For testing purposes only.
- Required: sweepstakes_token (UUID), email (string), phone (string, digits only for US), fields (object with form fields using underscores for spaces, e.g. {"First_Name": "John", "Last_Name": "Doe"})
- Optional: bonus_entries (number, default 0)

### get_participant
Fetch full details of a single participant by token, email, or phone. At least one search parameter required.
- Required: sweepstakes_token (UUID)
- Optional (at least one): participant_token (UUID), email (string), phone (string, 10 digits)

### fetch_participants
Get a paginated list of participants (20 per page). Supports search and date filtering.
- Required: sweepstakes_token (UUID)
- Optional: search (string), opt_in_date (YYYY-MM-DD), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), page (number)

### count_participants
Get participant counts with filtering.
- Required: sweepstakes_token (UUID)
- Optional: filter_type (all|participants|amoe|optouts), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD)

### update_bonus_entries
Update the bonus entries count for a specific participant.
- Required: sweepstakes_token (UUID), participant_token (UUID), bonus_entries (number)

### delete_participant
Permanently delete a participant from a sweepstakes.
- Required: sweepstakes_token (UUID), participant_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Entry Page Tools (3 tools)

### get_entry_fields
Get all form fields for a sweepstakes entry page. Call before add_participant to discover required fields. Returns field names, types, and whether they are required.
- Required: sweepstakes_token (UUID)

### get_entry_settings
Get all entry page settings: display, colors, compliance (terms, age gate, AMOE), confirmation, winners disclosure, and security toggles.
- Required: sweepstakes_token (UUID)

### update_entry_settings
Update entry page settings (max 5 fields per call). Top-level fields in PascalCase. Color fields use {"hexa": "#RRGGBB"} format. Prize amounts are NOT editable via this tool — never simulate a prize change by writing amounts into display text (headline/description); prize changes go through Sweeppea support.
- Required: sweepstakes_token (UUID), plus any of the entry page settings fields (max 5 per call)

---

## Group Tools (4 tools)

### fetch_groups
Get all groups from a sweepstakes. Groups are used to organize and segment participants.
- Required: sweepstakes_token (UUID)

### create_group
Create a new group within a sweepstakes.
- Required: sweepstakes_token (UUID), group_name (string, must be unique within the sweepstakes)

### update_group
Update the name of an existing group.
- Required: sweepstakes_token (UUID), group_token (UUID), group_name (string)

### delete_group
Permanently delete a group. Cannot delete primary groups, locked groups, or groups with participants.
- Required: sweepstakes_token (UUID), group_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Notes Tools (5 tools)

### fetch_notes
Get all notes for your account. Notes are automatically decrypted and returned in reverse chronological order.
- Parameters: none

### get_note
Get a single note by its token, with content automatically decrypted.
- Required: note_token (UUID)

### create_note
Create a new note. Content is automatically encrypted using AES-256-CBC encryption before storage.
- Required: title (string, max 100 chars, must be unique), content (string, max 100,000 chars)
- Optional: pinned (boolean, default false)

### update_note
Update an existing note. Supports partial updates.
- Required: note_token (UUID)
- Optional: title (string), content (string), pinned (boolean)

### delete_note
Permanently delete a note.
- Required: note_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Calendar Tools (5 tools)

### fetch_calendar_events
Get all calendar events for your account with dates, times, location, and status.
- Parameters: none

### get_calendar_event
Get a single calendar event by its token.
- Required: event_token (UUID)

### create_calendar_event
Create a new calendar event with title, dates, and optional details.
- Required: title (string), start_date (ISO 8601), end_date (ISO 8601)
- Optional: description, location, start_time (HH:MM), end_time (HH:MM), all_day (boolean), color (hex), event_url, latitude, longitude, notification, people_involved, private_event, repeat_this_event, sms_notification, status, completed

### update_calendar_event
Update an existing calendar event. Supports partial updates. Cannot update events to past dates.
- Required: event_token (UUID)
- Optional: title, start_date, end_date, start_time, end_time, description, location, all_day, color, event_url, latitude, longitude, notification, people_involved, private_event, repeat_this_event, sms_notification, status, completed

### delete_calendar_event
Permanently delete a calendar event.
- Required: event_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Rules Tools (5 tools)

### fetch_rules
Get all official rules for a sweepstakes including primary and secondary rules.
- Required: sweepstakes_token (UUID)

### create_rule
Create a new official rules document for a sweepstakes. Publishes free-form HTML WITHOUT the wizard's legal safeguards — prefer create_rules_wizard; requires explicit user confirmation and a user/counsel-reviewed document.
- Required: sweepstakes_token (UUID), title (string, max 100 chars), document_content (HTML string, max 1,000,000 chars)

### update_rule
Update an existing official rules document. Supports partial updates. Replacing document_content bypasses the wizard safeguards — requires explicit user confirmation.
- Required: sweepstakes_token (UUID), rules_token (UUID)
- Optional: title (string), document_content (HTML string), abbreviated_rules_shopify (string)

### delete_rule
Permanently delete an official rules document.
- Required: sweepstakes_token (UUID), rules_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

### create_rules_wizard
Generate official sweepstakes rules via 14-step wizard. Complete HTML rules are generated server-side.
- Required: sweepstakes_token (UUID), arv (1=>=5000, 2=<5000), alcohol_sweeps (1=sponsor produces/manufactures alcohol, 2=no — retailers/bars that merely sell alcohol are 2), nicotine_tobacco_sweeps (1=involves tobacco/nicotine/vaping, 2=no — NO producer/retailer split here: selling is enough; 1 forces min_age=2 and states=4 excluding MA, MI and VA, which ban tobacco sweepstakes; the prize may never be the product itself, per the federal free sample ban), sponsor_data_confirmed (boolean, must be true — asserts the user saw and approved the exact sponsor block that gets published), sweepstakes_name (6-60 chars), start_date, start_time, start_timezone, end_date, end_time, end_timezone, prize_description (max 5000 chars), prize_include_travel (boolean), prize_is_vehicle (boolean), prize_value (USD >0), entry_period_selector (1=single, 2=multiple), sponsor_name, sponsor_address, sponsor_city, sponsor_state, sponsor_zip_code, method_of_entry (1=Website, 2=SMS, 3=Social, 4=Other, 5-8=Purchase/Donation/Subscription), min_age (1=18+, 2=21+, 3=13+), states (1=48 contiguous US+DC, 2=50 US+DC, 3=+USVI+PR, 4=specific states, 5=50 US+DC excl FL/NY, 6=excl FL/NY/RI, 7=+Canada, 8=+Canada excl FL/NY, 9=+Canada excl FL/NY/RI, 10=Canada only), privacy_policy_url, sweeppea_entry_page (1=hosted, 2=custom, 3=none)
- Guardrails: URL fields on reserved placeholder domains (example.com, .example, .test, .invalid) are rejected; a sponsor_email equal to the account owner email is rejected unless sponsor_email_is_account_owner=true
- Conditional: winner_drawing_date, winners_to_draw (when entry_period_selector=1), entry_period_items (when entry_period_selector=2), social_media_entry_description (when method_of_entry=3), other_description (when method_of_entry=4), list_of_states (when states=4), custom_entry_page (when sweeppea_entry_page=2)

---

## Billing & Wallet Tools (4 tools)

### fetch_wallet_transactions
Get all wallet transactions including credits, debits, and payment details.
- Parameters: none

### fetch_billing_transactions
Get all billing transactions including invoices, amounts, and status. Sorted by creation date (newest first).
- Parameters: none

### fetch_billing_consumptions
Get monthly and yearly billing consumption totals. Shows aggregated usage data.
- Parameters: none

### fetch_data_transfer
Get data transfer records for a specific sweepstakes including bytes transferred, payment status, and rates.
- Required: sweepstakes_token (UUID)

---

## Support Tickets Tools (7 tools)

### fetch_open_tickets
Get open support tickets with pagination (20 per page) and search.
- Optional: search (string), platform (renaissance|api|general|overture|winners), priority (1=Low, 2=Medium, 3=High), page (number)

### fetch_closed_tickets
Get closed/resolved support tickets with pagination (20 per page) and search.
- Optional: search (string), platform (string), priority (1-3), page (number)

### get_ticket
Get full details of a support ticket by case number including notes, files, and collaborators.
- Required: case_number (string, e.g. "HYXTNJV")

### create_ticket
Create a new support ticket.
- Required: title (string, max 200 chars), description (string, max 20,000 chars), priority (1=Low, 2=Medium, 3=High)

### resolve_ticket
Close/resolve an open support ticket.
- Required: case_id (string)

### update_ticket
Update an open support ticket. Only open tickets can be updated.
- Required: case_id (string)
- Optional: title (string), description (string)

### delete_ticket
Permanently delete an open support ticket. Only open tickets can be deleted.
- Required: case_id (string), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Winner Tools (5 tools)

### draw_winners
Draw winners from a sweepstakes immediately. Uses weighted random selection favoring participants with bonus entries.
- Required: sweepstakes_token (UUID), how_many_winners (number >=1), group (UUID or "allgroups")
- Optional: completed_entries (boolean, default true), exclude_spam (boolean, default true), include_opted_out (boolean, default false)

### fetch_winners
Get winners from a sweepstakes with pagination. Sorted by draw date (most recent first).
- Required: sweepstakes_token (UUID)
- Optional: search (string), page (number), items_per_page (number, default 10)

### schedule_drawing
Schedule a future winner drawing.
- Required: sweepstakes_token (UUID), group (UUID or "allgroups"), selected_action (1=Draw only, 2=Draw & Notify), schedule_mode ("schedule"|"settime"), how_many_winners (number >=1), end_date (YYYY-MM-DD), end_time (HH:mm), timezone (number, default 7=Eastern)
- Optional: frequency (0=None, 1=Hourly, 2=Daily, 3=Weekly, 4=Monthly), day_of_the_week (1-7), week_of_the_month (1-4), delivery_time, message, publish_to_winners_page, send_copy_to_me, add_to_calendar, exclude_spam, include_opted_out

### fetch_scheduled_drawings
Get all scheduled drawings for a sweepstakes. Sorted by creation date (newest first).
- Required: sweepstakes_token (UUID)

### delete_scheduled_drawing
Delete a pending scheduled drawing. Only drawings with pending status can be deleted.
- Required: sweepstakes_token (UUID), schedule_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Documentation Tools (1 tool)

### fetch_documentation
Get help and support documentation articles. Supports pagination and search by title or content.
- Optional: page (number, default 1), limit (number, max 10, default 5), search (string)

---

## Utilities Tools (5 tools)

### fetch_timezones
Get all available timezones with IANA identifiers, abbreviations, and UTC offsets. Default timezone ID is 7 (Eastern Standard Time - America/New_York).
- Parameters: none

### fetch_states
Get all US states including DC, Puerto Rico, and US territories. Returns full names and two-letter abbreviations.
- Parameters: none

### fetch_zipcodes
Search US zip codes by zip code, city, or state name. Returns up to 10 results.
- Required: search (string)

### fetch_areacodes
Search US telephone area codes by code number or state name. Returns up to 10 results.
- Optional: search (string)

### fetch_countries
Search countries by name, international dial code, or ISO abbreviation. Returns up to 10 results with English/Spanish names.
- Optional: search (string)

---

## To-Do Tools (4 tools)

### create_todo
Create a new to-do item (admin only).
- Required: title (string), description (string)
- Optional: priority (string), due_date (ISO date), assigned_to (string)

### fetch_todos
Get all to-do items for the account (admin only).
- Parameters: none

### update_todo
Update an existing to-do item.
- Required: todo_token (UUID)
- Optional: title (string), description (string), priority, due_date, status, assigned_to

### delete_todo
Permanently delete a to-do item.
- Required: todo_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Files Tools (5 tools)

### upload_file
Upload a file to the user's Drive (base64-encoded, max 10MB). Supports PDF, DOC, images, and more.
- Required: filename (string), mime_type (string), file_data (string, base64)
- Optional: private (boolean)

### fetch_files
List all files in the user's Drive with storage usage, categories, and pagination.
- Optional: page (number), limit (number, max 200)

### delete_file
DESTRUCTIVE — IRREVERSIBLE. Permanently delete a file from the user's Drive and S3 storage. Requires explicit user confirmation.
- Required: file_token (string), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

### send_file
Send a file from the user's Drive as an email attachment (max 5MB) using the Sweeppea template.
- Required: file_token (string), recipient_email (string)
- Optional: email_subject (string), email_message (string)

### get_file_url
Generate a short-lived presigned S3 URL to download or preview a file from the user's Drive. The URL embeds the correct Content-Type and Content-Disposition headers; the actual transfer happens directly between the client and S3.
- Required: file_token (string)
- Optional: mode (string, "preview" or "download", default "preview"), expires_in (number, 60-3600 seconds, default 900)

---

## Testing Tools (1 tool)

### hello_world
Returns a simple Hello World greeting message. Used to verify MCP connection is working.
- Optional: name (string)

---

## Invoice Tools (5 tools)

Requires the Invoices module enabled on the account (disabled by default). A 403 "module is not enabled" error means the user must contact Sweeppea support — do not retry.

### create_invoice
Create a new invoice. Subtotal, tax and total are computed server-side (total must be $1–$1,000,000). Creating an invoice never notifies the recipient.
- Required: bill_to (object, PascalCase keys, Name and Email required), items (array of {Description required, Quantity, Rate}, max 60)
- Optional: title (max 200 chars), issue_date (YYYY-MM-DD), due_date (YYYY-MM-DD), discount_amount (number), tax_enabled (boolean), tax_label (string), tax_rate (0-100), payment_method (card|check|transfer), payment_instructions (string), notes_to_recipient (max 3000 chars), terms (max 3000 chars), status (draft|pending, default draft)

### fetch_invoices
Paginated list of invoices with filters. The Summary block covers the entire filtered set, not just the current page.
- Optional: status (draft|pending|paid|cancelled), from_date (YYYY-MM-DD), to_date (YYYY-MM-DD), page (default 1), limit (default 50, max 200)

### get_invoice
Full detail of a single invoice: line items, payment info, public link, QR code, stats and event timeline (max 200 events).
- Required: invoice_token (UUID)
- Optional: include_events (boolean, default true), include_qr_code (boolean, default true)

### update_invoice
Partial update of an editable invoice. items and bill_to are replaced as a whole when sent. State machine: draft → pending → paid, cancelled from draft/pending; reverting to draft is rejected; paid/cancelled invoices are immutable (409).
- Required: invoice_token (UUID)
- Optional: bill_to, items, title, issue_date, due_date, discount_amount, tax_enabled, tax_label, tax_rate, payment_method, payment_instructions, notes_to_recipient, terms, status (pending|cancelled)

### delete_invoice
Permanently delete an invoice. IRREVERSIBLE — not the same as cancelling. Wallet transactions and commissions from paid invoices are never deleted.
- Required: invoice_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)

---

## Survey Tools (7 tools)

Requires the Surveys module enabled on the account (disabled by default). A 403 "module is not enabled" error means the user must contact Sweeppea support — do not retry.

### create_survey
Create a survey attached to a sweepstakes, optionally with its full question set. Limits: 5 questions/page, 50 pages, 250 questions, 30 options/question. Validation is all-or-nothing.
- Required: sweepstakes_token (UUID), survey_name (max 200 chars)
- Optional: status (boolean, default true), settings (object, PascalCase keys), questions (array of {QuestionText required, FieldType required: text|textarea|radio|checkbox|select|slider|rating|nps|yesno|date, Page, QuestionDescription, Layout, Required, Options, Settings})

### fetch_surveys
Paginated list of surveys. IsLocked is true when the survey has responses (question structure can no longer be replaced).
- Optional: sweepstakes_token (UUID), status (boolean), archived (boolean), page (default 1), limit (default 50, max 200)

### get_survey
Full detail of a single survey including the complete question set (sorted by Page then Order, no pagination).
- Required: survey_token (UUID)

### update_survey
Partial update of a survey. questions is a FULL replacement of the question set and is rejected with 409 when responses exist. Use status false to disable without losing data.
- Required: survey_token (UUID), plus at least one of: survey_name, status, archived, settings, questions

### delete_survey
Permanently delete a survey with its questions, responses, stats and files. IRREVERSIBLE. confirm=true is required when the survey already has responses.
- Required: survey_token (UUID), confirm (boolean, must be true — the server rejects the call without explicit user confirmation)
- Optional: confirm (boolean)

### fetch_survey_responses
Individual responses with answers, newest first. include_metadata adds PII (IP, user agent, device) — default false.
- Required: survey_token (UUID)
- Optional: completed (boolean), from_date (YYYY-MM-DD), to_date (YYYY-MM-DD), include_metadata (boolean, default false), page (default 1), limit (default 25, max 100)

### fetch_survey_report
Aggregated report: totals, completion rate and times, device/browser breakdown, daily timeline, per-question distributions (capped at 25 buckets).
- Required: survey_token (UUID)
- Optional: timeline_days (number, default 30, max 365)

---

## Supported Platforms

### 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
Add to claude_desktop_config.json (requires Node.js):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

### Cursor
Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
Uses "url" key with "headers" object.

### Windsurf
Config file: ~/.codeium/windsurf/mcp_config.json
Uses "serverUrl" key with "headers" object.

### GitHub Copilot (VS Code)
Config file: .vscode/mcp.json (workspace) or User Settings
Supports promptString inputs for secure API key entry.

### Gemini CLI
Config file: ~/.gemini/settings.json (global) or .gemini/settings.json (project)
Uses "httpUrl" key with "headers" object.

### Agent Zero
Configure via Settings > MCP/A2A > MCP Servers
Uses "type": "streamable-http" with "url" and "headers".

### Antigravity by Google
Config file: ~/.gemini/antigravity/mcp_config.json
Uses npx mcp-remote bridge.

---

## About Sweeppea

Sweeppea is a full-service and self-service sweepstakes platform. The MCP Server extends the platform with AI-powered management capabilities, allowing users to manage sweepstakes campaigns entirely through natural language via AI assistants.

- Website: https://www.sweeppea.com
- MCP Docs: https://mcpdocs.sweeppea.com/
- MCP Endpoint: https://mcp.sweeppea.com/

## The Sweeppea Developer Ecosystem

Three clients, one platform, one API key. All of them talk to the Sweeppea REST API v3.

- MCP server (this document) — for AI assistants: https://mcpdocs.sweeppea.com/ · llms.txt: https://mcpdocs.sweeppea.com/llms.txt
- CLI — for shells and CI, `npx @sweeppea/cli`: https://clidocs.sweeppea.com/ · llms.txt: https://clidocs.sweeppea.com/llms.txt
- REST API v3 — direct HTTP integration: https://apidocs.sweeppea.com/ · OpenAPI: https://apidocs.sweeppea.com/openapi.json