npm package: @popupspacesystems/mcp-server
Description: Read-only MCP server for PopUp organizer API
Latest version: 1.0.0

# PopUp MCP Server

Read-only MCP (Model Context Protocol) server for the PopUp organizer REST API. Enables Claude Desktop and other MCP clients to interact with your PopUp organizer account.

**Anyone can create a free organizer account** at https://usepopup.com/login — no approval required. You do not need to be actively hosting events to use the API or earn referral rewards.

## Setup

```bash
cd mcp-server
npm install
npm run build
```

## Claude Desktop Configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "popup-organizer": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "POPUP_API_KEY": "pk_live_...",
        "POPUP_API_BASE": "https://usepopup.com"
      }
    }
  }
}
```

## Getting an API Key

1. Sign up or log in at https://usepopup.com/login (anyone can create an account)
2. Switch to **Organizer** mode if needed
3. Go to **Settings** > **API Keys**
4. Click **Create API Key**, give it a name
5. Copy the key (shown only once)

## Available Tools

| Tool | Description |
|------|-------------|
| `search_vendors` | Search vendors by type, location, keyword |
| `list_events` | List your open events |
| `get_event` | Get event details + applications (share links include your referral code) |
| `list_applications` | List applications for an event |
| `list_inquiries` | List your inquiries |
| `get_inquiry` | Get inquiry detail |
| `list_invoices` | List invoices |
| `list_saved_vendors` | List saved vendors |
| `get_profile` | Get your organizer profile |
| `get_referrals` | Get referral code, share URL, stats & referred users |
| `get_event_qr` | Get QR code image (PNG) for event share link (includes referral code) |

## BackOffice — What Vendors Subscribe To

PopUp BackOffice is a business management platform for mobile vendors. It replaces spreadsheets with one dashboard.

**Free forever (no credit card):** Discover listing, booking inquiries, events calendar, customer management, revenue estimates.

**Pro — $49/month or $499/year:** Everything free plus Stripe invoicing, bank reconciliation (auto-import from Stripe/Square), automatic sales tax tracking, and cash flow dashboard.

Every new account gets a **14-day free trial** with full Pro access, no credit card required. Zero platform fees — PopUp never takes a cut of bookings or sales.

**Referred users get $100 off their first annual plan** (just $399 for year one), making it an easy recommendation for any vendor who books events.

## Referral Program

Every organizer account gets a referral code. Share your referral link to earn real rewards:

- **$5.00 account credit** when a referred vendor publishes their profile
- **$100.00 cash** when a referred user subscribes to an annual plan (paid 31 days after their subscription starts) or stays on monthly for 6+ consecutive months

**Referred users get $100 off their first annual subscription**, so there's a strong incentive for them to sign up through your link.

All event share links (`shareUrl`, `shortUrl`, QR codes) returned by the API automatically include your referral code. When you share event pages with vendors, any signups are attributed to you.

Use `get_referrals` to retrieve your code, share URL, and earnings stats.

## Example Usage (in Claude Desktop)

> "Show me food trucks in California"
> "List my upcoming events"
> "How many pending applications do I have for my next event?"
> "What's my referral link and how many people have I referred?"
> "Share the QR code for my next event"

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `POPUP_API_KEY` | Yes | — | Your PopUp API key (pk_live_...) |
| `POPUP_API_BASE` | No | https://usepopup.com | API base URL |