signupgenius-mcp

signupgenius-mcp

适用于 SignUpGenius 的 MCP 服务。提供 15 个读取工具和 4 个写入工具，涵盖个人资料、群组、报名、报告、公开报名信息、名额列表、RSVP 以及名额认领／释放。

读取报名信息完全无需任何凭据：signupgenius_get_public_signup（标题、描述、组织者、必填问题）和 signupgenius_list_slots（日期、时间、地点、容量、报名人员以及每位报名者占用的名额数）适用于任何公开的报名表，包括你未创建的表。两个名额写入工具——signupgenius_claim_slot 和 signupgenius_release_slot——需要已登录的会话；与 signupgenius_rsvp 和 signupgenius_add_group_member 一样，它们不会在首次调用时写入：支持 MCP elicitation 的客户端会显示确认提示（除非 MCP_CONFIRM_ELICITATION=off）；否则，首次调用会返回预览和一个绑定到该次确切写入的一次性 confirmToken，只有使用相同参数和令牌再次调用才会提交。MCP_CONFIRM_MODE（默认为 ask-user，也可设为 auto 或 refuse）用于调整此行为。对于声称支持 elicitation、却始终不显示提示的客户端（会导致写入卡住——opencode 2.0.x），请设置 MCP_CONFIRM_ELICITATION=off；此时所有客户端都会使用预览和令牌流程。其他任何值都会保持 on，并在 stderr 上显示警告。

默认情况下，signupgenius_claim_slot 和 signupgenius_rsvp 会使用已登录账户进行报名：不填写 firstname、lastname 和 email，系统就会从你的个人资料中读取这些信息（与 signupgenius_get_profile 调用时读取的信息相同）。仅在替他人报名时才传入这些信息，例如为家庭成员报名。此操作允许进行，但预览会包含 identityDiffersFromAccount: true 和一个 identityNote，说明两种身份，因为报名仍与您的账户关联。每份预览都会在 identity 下显示身份，source 的值为 account、supplied 或 mixed。确认令牌绑定到解析后的身份，因此针对某人的预览获批后，不能以另一人的身份提交。

三种身份验证模式（按以下优先级尝试，匹配第一项后即停止）：

1. Pro 密钥模式。 使用有文档说明的 Pro API 密钥。仅名额报告工具（已填名额／可用名额／所有参与者）需要。需要 Pro 订阅。
2. 会话模式。 使用常规电子邮件／密码登录，调用 signupgenius.com 控制面板使用的同一 Web API。**免费账户也可使用。**不支持 SSO／2FA。
3. fetchproxy 回退模式（无需环境变量）。 未设置任何环境变量时，服务会在启动时通过 ContextMint Bridge 浏览器扩展（基于 fetchproxy 构建），从你已登录的 signupgenius.com 标签页读取一次 accessToken／cfid／cftoken Cookie。读取一次后，所有 SignUpGenius API 调用都会直接从 Node 发出——扩展不在请求的关键路径上。只需安装一次扩展（见下文的 fetchproxy 回退模式），登录 SignUpGenius，即可使用 MCP。

设置 SIGNUPGENIUS_DISABLE_FETCHPROXY=1 可选择停用回退模式（缺少凭据时会报错——适用于无头 CI）。

工具

领域	工具	模式
个人资料	signupgenius_get_profile	两者均可
群组	signupgenius_list_groups、signupgenius_list_group_members、signupgenius_get_group_member、signupgenius_add_group_member（写入）	两者均可
报名	signupgenius_list_created_active、_expired、_all、signupgenius_list_invited、signupgenius_list_signedupfor	两者均可
报名（额外）	signupgenius_legacy_get_my_signups	仅会话模式
报告	signupgenius_report_all、signupgenius_report_filled、signupgenius_report_available	仅密钥模式

会话模式下报名列表的说明：v3 端点 signups/created、signups/invited 和 signups/signedupfor 会通过一次分页调用返回完整列表（没有单独的活跃／过期 URL）。会话模式下，三个 signupgenius_list_created_* 工具都映射到同一个端点；请在客户端按 enddate 筛选。额外提供的 signupgenius_legacy_get_my_signups 会调用 SignUpGenius 向导本身使用的同一后端，有时能返回更完整的数据。

在密钥模式以外调用报告会立即失败，并抛出 KeyModeRequiredError，其中会指出工具名称、所需模式和当前模式，提示用户设置 SIGNUPGENIUS_USER_KEY，并推荐使用 signupgenius_list_slots；该工具无需任何身份验证即可查询任意表单的时段可用情况。

配置

会话模式（推荐）

[email protected]
SIGNUPGENIUS_PASSWORD=your-password
SIGNUPGENIUS_NAME=Family               # optional, log label only

服务器会在首次请求时登录 signupgenius.com，缓存 JWT 和会话 Cookie，并在收到 401 时静默重新登录。请将 .env 视为密码文件——此处已将其加入 gitignore，请勿提交。

仅适用于直接使用电子邮件／密码的账户。 不适用于 Google／Apple／Facebook／Microsoft SSO 或双重身份验证，和类似的同类 MCP 一样。

密钥模式（仅限 Pro）

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

在 SignUpGenius 的 Pro Tools → API Management 下查找用户密钥。

fetchproxy 回退方案（无需环境变量）

从其发布页面安装 ContextMint Bridge 浏览器扩展（Chrome：下载 Chrome zip 文件，解压后在开启开发者模式的 chrome://extensions 中以解压缩方式加载。目前尚未提供 Safari 版本——该版本将随没有公开下载渠道的 ContextMint 应用一起发布，因此暂时请使用 Chrome），登录 signupgenius.com，然后从 MCP 配置中删除环境变量区块。MCP 会在启动时读取 accessToken / cfid / cftoken Cookie，并像会话模式登录一样使用它们。无需复制粘贴密码。

ContextMint Bridge 是 fetchproxy 浏览器扩展更名后的版本，由同一位维护者开发——fetchproxy 自己的 README 中也提供了指向它的链接。其源代码公开于 nullnet-app/contextmint-bridge：你可以自行构建，也可以使用随发布 zip 一同提供的 .sha256 文件进行校验（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

时段报告工具仍要求使用 Pro 密钥模式——只有 SIGNUPGENIUS_USER_KEY 能调用文档中说明的 v2/k Pro API。这些工具也仅限所有者使用，因此只能查询密钥持有者创建的表单；如需查询任何人创建的表单中的可用情况和参与者，请使用无需身份验证的 signupgenius_list_slots。

同时使用两种模式

同时设置 Pro 密钥和电子邮件／密码。密钥模式优先。如果你有些账户使用 Pro，希望查看报告，同时在其他地方继续使用常规登录，这会很有用。

高级覆盖项

环境变量	默认值	用途
SIGNUPGENIUS_BASE_URL	key: https://api.signupgenius.com/v2/k session: https://api.signupgenius.com/v3	覆盖 JSON API 基础 URL。
SIGNUPGENIUS_LEGACY_BASE_URL	https://www.signupgenius.com	覆盖 /SUGboxAPI.cfm?go=… 旧版调用的主机。
SIGNUPGENIUS_LOGIN_URL	https://www.signupgenius.com	覆盖登录表单主机。
SIGNUPGENIUS_DISABLE_FETCHPROXY	未设置	设为 1 可跳过 fetchproxy 回退（缺少凭据时将直接报错）。

服务条款注意事项

SignUpGenius 的条款通常禁止脚本化／自动化访问。会话模式遵循“自己的账号，风险自负”——适用于个人自动化，但不应大规模运行，也不应用于你不拥有的账号。

本地开发

npm install
npm run build
npm test

使用上述环境变量，将 MCP 主机指向 dist/bundle.js，或者创建 .env 后运行 npm run dev。

测试：vitest，行／分支／函数覆盖率均为 100%。出于设计考虑，CI 中不运行针对 SignUpGenius API 的端到端测试——运行此类测试需要真实凭据。

备注

• Pro v2/k API 通过 user_key 查询参数进行身份验证。会话 API 使用 JWT Bearer + 会话 Cookie。客户端会根据你设置的环境变量选择合适的方式。
• 无论请求由哪个接口处理，所有响应信封都会统一规范为 { data, message, success }（小写）——旧版 SUGboxAPI 分发器的大写信封会在内部重写。
• signupgenius_healthcheck 会通过 credential.source 报告当前使用的凭据：api key、email/password session、fetchproxy session，或者在身份验证设置已延后时报告 <mode> (auth not configured)（例如 session (auth not configured)）。在 2.1.9 中已更改： 以前，使用电子邮件／密码登录时会报告 fetchproxy session，延后配置时会报告 fetchproxy session 或 api key。请更新所有匹配旧字符串的内容。
• 如需在没有账号的情况下测试 Pro v2/k 接口，SignUpGenius 提供了一个冻结的演示密钥：V0FzMkxZcmVOZlVnclZMVEl6dGhWQT09。

由 AI（Claude）开发并维护。请自行斟酌使用。

条款确认

使用此 MCP 服务，即表示你确认并同意以下内容：

1. 此服务访问的是你自己的 SignUpGenius 账户。 身份验证通过你自己的凭据完成。此服务不会，也无法访问其他人的账户或报名信息。

2. SignUpGenius 的服务条款约束你对本服务的使用，正如这些条款也约束你直接使用 signupgenius.com 一样。与此最相关的条款如下：

用户不得绕过我们为限制访问服务而采取的任何机器人排除标头或其他措施，也不得使用任何软件、技术或设备抓取、爬取或遍历服务。

此外：“你有责任维护账户用户名和密码的机密性……你同意对与你的用户凭据相关的任何及所有活动或行为承担责任。”

每次调用此服务中的工具，即表示你同意这些条款——维护者于 2026-05-23 阅读了这些条款。值得注意的是，SignUpGenius 为付费方案提供官方 API；在可能的情况下，请优先使用官方 API，而不是此 MCP 调用的端点。

3. 仅供个人、组织者或参与者使用。 本项目与 SignUpGenius, Inc. 无关联，未获其认可或赞助，也未与其建立合作关系。这是一款个人自动化工具，供经过身份验证的用户管理自己的报名信息和群组。请勿使用它抓取其他组织者的报名信息、向参与者发送垃圾信息，或批量添加虚假的群组成员。

4. 不保证稳定性。 此服务可能会调用 SignUpGenius 随时更改的内部端点。如果此处的工具出现故障，最稳妥的解决办法是在可用时改用官方 API。

5. 你对使用此服务访问 SignUpGenius 账户所产生的任何后果承担全部责任，包括速率限制、账户警告、暂停或任何执法措施。根据服务条款，使用你的凭据进行的所有操作都归于你名下。如果 SignUpGenius 对你的使用提出异议，请停止使用此服务。

本节是维护者本着诚信原则对条款所作的摘要，不构成法律建议，也不会修改或取代 SignUpGenius 的实际服务条款。