# Sweeppea MCP Server — Full Documentation

> Sweeppea MCP Server is a Model Context Protocol (MCP) server for AI-powered sweepstakes management. It provides 53+ tools across 13 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 all sweepstakes associated with your account. Returns a list of all sweepstakes with their details.
- Parameters: none

### create_sweepstakes
Create a new sweepstakes programmatically.
- Required: sweepstakes_name (string), sweepstakes_type (1=SMS, 2=Email, 3=Social), 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)
- Optional: create_in_calendar (boolean), sync_with_winners (boolean), delete_if_deleted (boolean), delete_if_acct_deleted (boolean)
- Limits: Maximum 3 active sweepstakes, 10 total (active + inactive)

### update_sweepstakes
Update an existing sweepstakes. Handler and type cannot be changed after creation.
- 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)

---

## Participant Tools (5 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), fields (object with form fields using underscores for spaces, e.g. {"First_Name": "John", "Last_Name": "Doe"})
- Optional: phone (string), 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)

### delete_participant
Permanently delete a participant from a sweepstakes.
- Required: sweepstakes_token (UUID), participant_token (UUID)

---

## Entry Page Tools (1 tool)

### 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)

---

## 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)

---

## Notes Tools (4 tools)

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

### 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)

---

## 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)

---

## 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.
- 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.
- 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)

### 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=yes, 2=no), 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-10 geographic options), privacy_policy_url, sweeppea_entry_page (1=hosted, 2=custom, 3=none)
- 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)

---

## 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)

---

## 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)

---

## Testing Tools (1 tool)

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

---

## 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/