# signupgenius-mcp

[![CI](https://github.com/chrischall/signupgenius-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/signupgenius-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/signupgenius-mcp)](https://www.npmjs.com/package/signupgenius-mcp)
[![license](https://img.shields.io/npm/l/signupgenius-mcp)](LICENSE)

MCP server for [SignUpGenius](https://www.signupgenius.com). 15 read tools and 4 write across profile, groups, sign-ups, reports, public sign-up metadata, slot listings, RSVPs, and slot claim/release.

Reading a sign-up needs **no credentials at all**: `signupgenius_get_public_signup` (title, description, organizer, required questions) and `signupgenius_list_slots` (dates, times, locations, capacity, who has signed up and how many spots each entry takes) work on any public sheet, including ones you did not create. The two slot writes — `signupgenius_claim_slot` and `signupgenius_release_slot` — need a signed-in session and, like `signupgenius_rsvp` and `signupgenius_add_group_member`, never write on the first call: a client that supports MCP elicitation gets a confirmation prompt (unless `MCP_CONFIRM_ELICITATION=off`); otherwise the first call returns a preview and a single-use `confirmToken` bound to that exact write, and only a repeat call with the same arguments plus the token submits. `MCP_CONFIRM_MODE` (`ask-user` default, `auto`, `refuse`) tunes this. Set `MCP_CONFIRM_ELICITATION=off` for a client that says it supports elicitation but never shows the prompt (the write hangs — opencode 2.0.x); every client then gets the preview-and-token flow. Any other value stays `on`, with a warning on stderr.

`signupgenius_claim_slot` and `signupgenius_rsvp` sign up **as the signed-in account by default**: leave `firstname`, `lastname` and `email` out and they are read from your profile (the same call `signupgenius_get_profile` makes). Pass them only to sign up someone else, such as a family member. That is allowed, but the preview then carries `identityDiffersFromAccount: true` and an `identityNote` naming both identities, because the entry is still tied to your account. Every preview shows the identity under `identity`, with `source` set to `account`, `supplied` or `mixed`. The confirm token is bound to the resolved identity, so a preview approved for one person can't submit as another.

Three auth modes (tried in this priority order — first match wins):
1. **Pro key mode.** Uses the documented Pro API key. Required only for the slot REPORT tools (filled/available/all-participants). Pro subscription needed.
2. **Session mode.** Logs in with your normal email/password to call the same web API the signupgenius.com dashboard uses. **Free accounts work.** No SSO/2FA.
3. **fetchproxy fallback (no env vars needed).** When no env vars are set, the server reads `accessToken` / `cfid` / `cftoken` cookies once at startup from your already-signed-in `signupgenius.com` tab via the [ContextMint Bridge](https://github.com/nullnet-app/contextmint-bridge/releases) browser extension (built on fetchproxy). After that one read, all SignUpGenius API calls go directly from Node — the extension is **not** in the request hot path. Install the extension once (see [fetchproxy fallback](#fetchproxy-fallback-no-env-vars) below), sign into SignUpGenius, and the MCP just works.

Set `SIGNUPGENIUS_DISABLE_FETCHPROXY=1` to opt out of the fallback (turns missing credentials into a hard error — useful in headless CI).

## Tools

| Domain | Tools | Mode |
|---|---|---|
| Profile | `signupgenius_get_profile` | both |
| Groups | `signupgenius_list_groups`, `signupgenius_list_group_members`, `signupgenius_get_group_member`, `signupgenius_add_group_member` (write) | both |
| Sign-ups | `signupgenius_list_created_active`, `_expired`, `_all`, `signupgenius_list_invited`, `signupgenius_list_signedupfor` | both |
| Sign-ups (extras) | `signupgenius_legacy_get_my_signups` | session only |
| Reports | `signupgenius_report_all`, `signupgenius_report_filled`, `signupgenius_report_available` | **key only** |

Notes on session-mode sign-up listings: the v3 endpoints `signups/created`, `signups/invited`, and `signups/signedupfor` return the full list in one paginated call (no separate active/expired URLs). The three `signupgenius_list_created_*` tools all map to the same endpoint in session mode; filter by `enddate` client-side. The bonus `signupgenius_legacy_get_my_signups` calls the same backend the SignUpGenius wizard itself uses and sometimes returns fuller data.

Reports outside key mode fail fast with a `KeyModeRequiredError` naming the tool, the mode required and the mode in effect, telling the user to set `SIGNUPGENIUS_USER_KEY` — and pointing at `signupgenius_list_slots`, which answers slot availability for any sheet with no auth at all.

## Configuration

### Session mode (recommended)

```
SIGNUPGENIUS_EMAIL=you@example.com
SIGNUPGENIUS_PASSWORD=your-password
SIGNUPGENIUS_NAME=Family               # optional, log label only
```

The server logs into signupgenius.com on first request, caches the JWT and session cookies, and silently re-logs in on a 401. Treat `.env` like a password file — it's gitignored here, do not commit.

**Direct email/password accounts only.** Won't work with Google/Apple/Facebook/Microsoft SSO or 2FA, same caveat as similar sibling MCPs.

### Key mode (Pro only)

```
SIGNUPGENIUS_USER_KEY=your-api-key
SIGNUPGENIUS_NAME=PTA Org              # optional
```

Find the user key in SignUpGenius under **Pro Tools → API Management**.

### fetchproxy fallback (no env vars)

Install the ContextMint Bridge browser extension from its [releases page](https://github.com/nullnet-app/contextmint-bridge/releases) (Chrome: download the chrome zip, unzip it and load it unpacked at `chrome://extensions` with Developer mode on. Safari isn't available yet — it will ship inside the ContextMint app, which has no public download — so use Chrome for now), sign into [signupgenius.com](https://www.signupgenius.com), and remove the env block from your MCP config. The MCP reads `accessToken` / `cfid` / `cftoken` cookies once at startup and uses them like a session-mode login. No password copy-paste required.

ContextMint Bridge is the fetchproxy browser extension under its new name, from the same maintainer — fetchproxy's own [README](https://github.com/chrischall/fetchproxy#extension) points to it. Its source is public at [nullnet-app/contextmint-bridge](https://github.com/nullnet-app/contextmint-bridge): build it yourself, or check a release zip against the `.sha256` file published beside it (`shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`).

The slot REPORT tools still require Pro key mode — `SIGNUPGENIUS_USER_KEY` is the only path that hits the documented v2/k Pro API. They are also **owner-scoped**, so they only answer for sheets the key holder created; for availability and participants on anyone's sheet use `signupgenius_list_slots`, which needs no auth.

### Both at once

Set both Pro key and email/password. Key mode wins. Useful if you have Pro for some accounts and want reports while still using your normal login elsewhere.

### Advanced overrides

| Env var | Default | Purpose |
|---|---|---|
| `SIGNUPGENIUS_BASE_URL` | key: `https://api.signupgenius.com/v2/k`<br>session: `https://api.signupgenius.com/v3` | Override the JSON API base. |
| `SIGNUPGENIUS_LEGACY_BASE_URL` | `https://www.signupgenius.com` | Override the host for `/SUGboxAPI.cfm?go=…` legacy calls. |
| `SIGNUPGENIUS_LOGIN_URL` | `https://www.signupgenius.com` | Override the login form host. |
| `SIGNUPGENIUS_DISABLE_FETCHPROXY` | unset | Set to `1` to skip the fetchproxy fallback (missing creds become a hard error). |

## ToS caveat

SignUpGenius's terms generally prohibit scripted/automated access. Session mode is "your own account, your own risk" — fine for personal automation but not something you should run at scale or on accounts you don't own.

## Local dev

```
npm install
npm run build
npm test
```

Point an MCP host at `dist/bundle.js` with the env vars above, or run `npm run dev` after creating a `.env`.

Tests: vitest, 100% line/branch/function coverage. End-to-end tests against the SignUpGenius API are not in CI by design — running them requires real credentials.

## Notes

- The Pro v2/k API authenticates via a `user_key` query param. The session API uses a JWT Bearer + session cookie. The client picks the right one based on which env vars you set.
- All response envelopes are normalized to `{ data, message, success }` (lowercase) regardless of which surface served the request — the legacy SUGboxAPI dispatcher's uppercase envelope is rewritten internally.
- `signupgenius_healthcheck` reports the credential in use as `credential.source`, one of `api key`, `email/password session`, `fetchproxy session`, or `<mode> (auth not configured)` (e.g. `session (auth not configured)`) when auth setup was deferred. **Changed in 2.1.9:** an email/password login used to report `fetchproxy session`, and a deferred config used to report `fetchproxy session` or `api key`. Update anything that matches on the old strings.
- For testing the Pro v2/k surface without an account, SignUpGenius publishes a frozen demo key: `V0FzMkxZcmVOZlVnclZMVEl6dGhWQT09`.

Developed and maintained by AI (Claude). Use at your own discretion.

## Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

**1. This server accesses your own SignUpGenius account.** Auth happens via your own credentials. It does not — and cannot — access anyone else's account or signups.

**2. [SignUpGenius's Terms of Service](https://www.signupgenius.com/terms-of-service) govern your use of this server**, just as they govern your direct use of signupgenius.com. The clauses most relevant here:

> Users may not bypass any robot exclusion headers or other measures we take to restrict access to the Services or use any software, technology, or device to scrape, spider, or crawl the Services.

And: *"You are responsible for maintaining the confidentiality of your account user name and password… You agree to accept responsibility for any and all activities or actions that occur in connection with your User Credentials."*

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Notably, **SignUpGenius does offer an official API** for paid plans; where possible, prefer the official API over the endpoints this MCP exercises.

**3. Personal, organizer/participant use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with SignUpGenius, Inc. It is a personal automation tool for an authenticated user to manage their own signups and groups. Do not use it to scrape other organizers' signups, spam participants, or bulk-add fake group members.

**4. Stability is not guaranteed.** This server may call internal endpoints that SignUpGenius can change without notice. If a tool here breaks, the canonical fix is to use the official API where available.

**5. You accept full responsibility** for any consequences of using this server in connection with your SignUpGenius account — rate limiting, account warnings, suspension, or any enforcement action. Per the ToS, everything done under your credentials is attributed to you. If SignUpGenius objects to your use, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede SignUpGenius's actual ToS.