Partiful by Cotlet

Partiful API 和 MCP 服务，可自托管

一个 Partiful API 和 Partiful MCP 服务，使用 Python 在你自己的电脑上运行，并通过你自己的 Google Chrome 会话访问。包含我们在 Cotlet 正式环境中使用的全部 14 个 Partiful 工具：活动、包含问卷答案的嘉宾名单、CSV 导出文件、签到、嘉宾审批、邀请和群发短信。

Partiful 没有公开 API，也没有官方 MCP 服务。此仓库同时提供两者：

• MCP 服务：可供 Claude Code、Claude Desktop、Cursor、Codex 和任何 MCP 客户端使用，支持 stdio 或 HTTP。设置
• REST API：地址为 http://127.0.0.1:8787/api/v1/partiful，OpenAPI 文档位于 /docs。设置
• Python：call("list_guests", event_id="...")，另附 examples/ 中的 9 个现成脚本。

此项目面向希望自行运行它的技术人员，仅供非商业用途（许可证）。如果你希望它在服务器上全天候运行，在 Partiful 网站发生变化时仍能正常工作，并供团队或企业使用，请使用 cotlet.dev 上的托管版本。

git clone https://github.com/cotletdev/partiful-api-mcp-server.git && cd partiful-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
partiful-mcp connect                                  # reads your Partiful session from Chrome
partiful-mcp call list_events
claude mcp add partiful -- "$PWD/.venv/bin/partiful-mcp" mcp

目录

• 工作原理
• 要求
• 安装
• 连接你的 Chrome
• MCP 服务
• REST API
• Python 和示例脚本
• 全部 14 个工具
• 配置
• 安全与 Partiful 账户
• 错误
• 自托管或托管服务
• 常见问题
• 许可证

工作原理

AI agent (MCP) / script (REST, Python) ──▶ partiful-mcp on your computer ──your Partiful sign-in──▶ api.partiful.com
                                                  ▲                                                 Firestore
                      partiful-mcp connect ───────┘ reads it once from your Chrome (DevTools Protocol)

1. 使用你的手机号码登录你自己的 Chrome 中的 Partiful，并输入 Partiful 发给你的验证码。
2. partiful-mcp connect 通过 Chrome DevTools Protocol 连接到该 Chrome。它会读取 partiful.com 的 Cookie，以及 Partiful 网页应用保存在 IndexedDB 中的已登录用户信息（Firebase 及其刷新令牌）。如果没有打开 Partiful 标签页，它会在后台打开一个，然后再将其关闭。这两项信息都会保存到 ~/.config/partiful-api-mcp/session.json，且只有你的用户可以读取。
3. 每次工具调用都会向 Partiful 网页应用自身调用的端点发送请求：api.partiful.com 上的函数，以及用于嘉宾名单和活动编辑的 Firestore。请求通过 curl_cffi 发出，它会复制 Chrome 的 TLS 指纹。整个过程不会运行无头浏览器。

Partiful 的登录令牌有效期为一小时。服务会按照网页应用的方式，从 Google 的 securetoken.googleapis.com 使用已保存的刷新令牌续期，因此你只需连接一次，无需每小时重新连接。当 Partiful 结束会话时，如果 Chrome 已打开远程调试，服务会再次从 Chrome 中读取会话信息。

要求

• Python 3.11 或更高版本。
• Google Chrome 144 或更高版本，并已在 partiful.com 登录 Partiful。任何启用了调试端口的 Chrome 或 Chromium 均可使用。
• macOS、Linux 或 Windows。
• 一个用于创建活动的 Partiful 账户。读取和更改活动的嘉宾名单、审批、签到、邀请和群发短信，仅适用于你主办或共同主办的活动。get_event 可以打开你账户能够查看的任何活动。

安装

git clone https://github.com/cotletdev/partiful-api-mcp-server.git
cd partiful-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
partiful-mcp --version

使用 uv：运行 uv venv && uv pip install -e .，然后运行 uv run partiful-mcp ...。

使用 AI Agent（Claude Code、Codex、Cursor）设置？在此文件夹中打开项目，并让它设置仓库：AGENTS.md 会告诉它每个步骤；只有在 Chrome 中操作的步骤才需要你来完成。

更新方式：运行 git pull && pip install -e .。我们会将托管版 Partiful 工具的所有变更复制到此仓库。

连接你的 Chrome

选项 A：日常使用的 Chrome（推荐）

1. 在 Chrome 中打开 chrome://inspect/#remote-debugging，并开启 远程调试。之后，Chrome 会接受此电脑上的程序发起的 DevTools 连接，并在每次连接前征求你的许可。

2. 确保你已登录 partiful.com。

3. 运行：

   partiful-mcp connect
   

4. Chrome 会询问是否允许连接。点击 允许。

Saved 16 Partiful cookies and 1 sign-in keys to /Users/you/.config/partiful-api-mcp/session.json
Signed in to Partiful as Maya Chen

之后可以再次关闭远程调试。如果你希望 Partiful 将你登出后，服务能自动获取新会话，请保持远程调试开启。

connect 会在 Chrome 的默认配置文件夹中查找 DevToolsActivePort 文件。对于 Chrome Beta、Canary 或自定义配置文件夹，请传入 --profile-dir "<folder>"。

选项 B：使用带调试端口的 Chrome

Chrome 不会在默认配置文件上开放调试端口，因此请另外启动一个 Chrome，在其中登录 Partiful 一次，然后连接到它：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-partiful"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-partiful"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-partiful"

partiful-mcp connect --cdp http://127.0.0.1:9222

--cdp 也接受 ws:// DevTools URL，例如通过 SSH 隧道连接到另一台机器上的 Chrome。

没有粘贴 Cookie 的选项。Partiful 的 API 从浏览器的 IndexedDB（而非 Cookie）中获取已登录用户，因此 connect 需要连接一次正在运行的 Chrome。之后会话文件即可独立使用，也能在没有 Chrome 的机器上使用。

随时检查会话：

partiful-mcp status

MCP 服务

MCP 服务会列出每个工具及其输入架构、面向 Agent 编写的描述和提示：读取工具会标记为只读；邀请、发消息、批准或删除的工具也会标记出来，以便客户端在运行前征求你的许可。

Claude Code

claude mcp add partiful -- /path/to/partiful-api-mcp-server/.venv/bin/partiful-mcp mcp
# read only:
claude mcp add partiful -- /path/to/partiful-api-mcp-server/.venv/bin/partiful-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "partiful": {
      "command": "/path/to/partiful-api-mcp-server/.venv/bin/partiful-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json，与 Claude Desktop 使用相同的配置段。可直接使用的副本位于 mcp.json。

Codex

~/.codex/config.toml：

[mcp_servers.partiful]
command = "/path/to/partiful-api-mcp-server/.venv/bin/partiful-mcp"
args = ["mcp"]

使用 HTTP

partiful-mcp serve 也会通过可流式传输的 HTTP 在 http://127.0.0.1:8787/mcp 上提供 MCP 服务，供接受 URL 的客户端使用：

partiful-mcp serve
claude mcp add --transport http partiful http://127.0.0.1:8787/mcp

然后可以向你的 Agent 提出诸如此类的问题：

谁会参加周五的晚餐？他们在问卷中填写了哪些饮食限制？

批准所有待处理的宾客，只要他们申请参加我的发布派对时填写了公司名称；并列出其余宾客。

复制上个月的读书会，安排在 11 月 14 日晚上 7 点，并邀请参加过的人。

给所有“会参加”或“可能参加”我屋顶晚餐的人发短信，告诉他们门禁密码是 4512。

REST API

partiful-mcp serve                    # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

每个工具在 /api/v1/partiful 下都有自己的路由，与 cotlet.dev 上托管 API 的路径相同，因此针对其中一个 API 编写的代码也适用于另一个。路径部分和查询字符串用作参数，JSON 请求体则补充其余参数。

curl 'http://127.0.0.1:8787/api/v1/partiful/events?when=past'
curl 'http://127.0.0.1:8787/api/v1/partiful/events/hK3vQ9xLm2Pa7RtYc4Wd/guests?status=going'
curl -X PATCH http://127.0.0.1:8787/api/v1/partiful/events/hK3vQ9xLm2Pa7RtYc4Wd \
  -H 'Content-Type: application/json' \
  -d '{"location": "21 Mercer St, New York"}'

按名称调用任意工具，并将请求体作为参数：

curl -X POST http://127.0.0.1:8787/api/v1/partiful/tools/list_guests -d '{"event_id": "hK3vQ9xLm2Pa7RtYc4Wd"}'

• GET /api/v1/partiful/tools：列出所有工具及其路由、输入架构和示例响应。
• GET /docs：交互式 OpenAPI 文档；GET /openapi.json：供 n8n、Postman 或生成的客户端使用的架构。
• 响应为 JSON。列表会返回 next_cursor；将其作为 cursor 传回即可获取下一页。

服务仅监听 127.0.0.1。如需从你的其他设备访问，请设置令牌；之后每个请求都需要提供 Authorization: Bearer <token>：

PARTIFUL_MCP_TOKEN=$(openssl rand -hex 24) partiful-mcp serve --host 0.0.0.0

Python 和示例脚本

直接使用 Python，无需服务端：

from partiful_api_mcp import call
from partiful_api_mcp.scripting import paginate, write_rows

events = call("list_events")["events"]
going = list(paginate("list_guests", {"event_id": events[0]["event_id"], "status": "going"}, "guests"))
write_rows(going, "going.csv")
call("update_event", event_id=events[0]["event_id"], location="21 Mercer St, New York")

或者在命令行中使用一个工具：partiful-mcp call list_guests event_id=hK3vQ9xLm2Pa7RtYc4Wd status=pending，也可以使用 JSON 对象。

examples/ 中提供了现成脚本。每个脚本都会输出 JSON 或文本，并在适用时接受 --out file.csv 或 --out file.json，还支持 --help：

脚本	功能
list_events.py	列出你主办的活动，以及日期、状态和各 RSVP 状态的宾客人数。--when past。
export_guest_list.py	保存与“导出 CSV”按钮相同的 CSV。--status going。
export_rsvps.py	将一个或多个活动的宾客导出为表格行，每个问卷问题对应一列。
questionnaire_summary.py	列出每个问卷答案、给出该答案的宾客人数及名单，以及尚未作答的宾客。
approve_pending_guests.py	批准答案符合 --match 关键词的待审批宾客，最多批准 --max 人。先使用 --dry-run 试运行。
check_in_guests.py	按姓名为宾客办理签到，或撤销签到。
list_past_guests.py	列出过去的宾客和可邀请的共同好友；使用 --not-on 指定不在某活动上的宾客。
reinvite_past_guests.py	将活动复制到新日期，并邀请之前表示会参加的人。先使用 --dry-run 试运行。
text_guests.py	向所选 RSVP 状态的宾客发送群发短信，并先显示覆盖人数。

python examples/export_guest_list.py --event hK3vQ9xLm2Pa7RtYc4Wd --status going --out rsvps.csv
python examples/approve_pending_guests.py --event hK3vQ9xLm2Pa7RtYc4Wd --match inc --dry-run

要按计划运行，只要电脑开机，使用本机的 cron 即可：0 8 * * 1 cd ~/partiful-api-mcp-server && .venv/bin/python examples/export_rsvps.py --event <id> --status going --out rsvps.csv。

全部 14 个工具

event_id 是活动链接中的 ID：对于 partiful.com/e/hK3vQ9xLm2Pa7RtYc4Wd，它是 hK3vQ9xLm2Pa7RtYc4Wd。list_events 会返回该 ID。partiful-mcp tools 会打印此列表，partiful-mcp tools --json 则会附上输入架构。

活动

工具	访问权限	REST 路由	功能
list_events	读取	GET /events	列出你主办的活动，以及日期、状态和宾客人数。
get_event	读取	GET /events/{event_id}	活动完整信息：标题、描述、开始和结束时间、地点、RSVP 截止时间、宾客人数上限、“宾客审批”和候补名单设置，以及链接。
create_event	写入	POST /events	创建新的活动页面。在调用 invite_guests 之前，不会邀请任何人。
update_event	写入	PATCH /events/{event_id}	修改你主办的活动详情或设置。
duplicate_event	写入	POST /events/{event_id}/duplicate	将活动及其设置复制到新的日期。副本暂时没有宾客。
cancel_event	写入	POST /events/{event_id}/cancel	取消活动。Partiful 会通知宾客。
delete_event	写入	DELETE /events/{event_id}	为所有人删除你主办的活动及其宾客名单。

宾客名单

工具	访问权限	REST 路由	功能
list_guests	读取	GET /events/{event_id}/guests	列出活动宾客及其 RSVP 状态、签到情况和“宾客问卷”答案。
export_guest_list	读取	GET /events/{event_id}/guests/export	将宾客名单导出为 CSV，与“导出 CSV”按钮生成的文件相同。
check_in_guests	写入	POST /events/{event_id}/guests/check-in	为到场宾客办理签到，或撤销签到。
approve_guests	写入	POST /events/{event_id}/guests/approve	批准启用了“宾客审批”的活动中的待审批宾客。

邀请和群发短信

工具	权限	REST 路由	功能
list_past_guests	读取	GET /past-guests	可邀请的人：过去的宾客和共同联系人。
invite_guests	写入	POST /events/{event_id}/guests/invite	通过 Partiful 邀请过去的宾客和共同联系人，也可通过电子邮件邀请任何人。
send_text_blast	写入	POST /events/{event_id}/text-blasts	按 RSVP 状态向宾客发送短信。Partiful 允许每场活动最多发送 10 条群发短信。

未实现：邀请电话号码（Partiful 仅在其应用中接受电话联系人）、拒绝或移除宾客、更改宾客的 RSVP、共同主持人、评论和照片、回复群发短信、门票、主题和 Discover。有意不实现：Partiful 登录、电话号码、姓名和个人资料，以及任何资金转移功能。每个请求都会经过一道防护检查，拒绝访问这些 Partiful 路径。

配置

变量	默认值	功能
PARTIFUL_MCP_HOME	~/.config/partiful-api-mcp	session.json 所在文件夹。
PARTIFUL_PROXY		所有发往 Partiful 的请求所用的代理，例如 http://user:pass@host:port。
PARTIFUL_MCP_READ_ONLY		1 会隐藏并拒绝所有会更改 Partiful 的工具（与 --read-only 相同）。
PARTIFUL_MCP_TOKEN		serve 所需的 Bearer 令牌；要监听 127.0.0.1 之外的地址时必须设置。
PARTIFUL_MCP_HOST、PARTIFUL_MCP_PORT	127.0.0.1、8787	serve 的地址。

安全与 Partiful 账户

• 无需验证码，无需密码。 Partiful 通过短信验证码为你登录。此代码不会向你索取验证码，而是读取 Chrome 已保存的会话。
• 会话文件归你所有。 session.json 创建时权限为 0600，其中包含 partiful.com Cookie 和 Firebase 刷新令牌。任何拿到它的人都能以你的身份操作 Partiful，因此请勿将其放入 Git 或共享文件夹。
• 默认仅限本地。 serve 绑定到 127.0.0.1；若要绑定其他地址，必须设置 PARTIFUL_MCP_TOKEN。
• 仅限三个主机。 请求和重定向仅会发往 partiful.com、securetoken.googleapis.com（令牌续期）和 firestore.googleapis.com（宾客名单、活动编辑）。
• 只读模式。 --read-only 或 PARTIFUL_MCP_READ_ONLY=1 仅开放 5 个读取工具。
• 操作会影响真实用户。 邀请、群发短信、审批和取消会立即发送到真实用户的手机和收件箱，而且群发消息无法撤回。MCP 客户端会在执行前询问；脚本不会，因此请先在测试活动中试用。
• 请勿发送垃圾信息。 Partiful 限制每场活动最多发送 10 条群发短信和 1,000 条邀请。你需对账户中运行的操作负责。

错误

REST API 会返回 {"error": "<code>", "message": "..."}。MCP 服务会将相同的代码和消息作为工具错误返回。

状态	代码	处理方法
401	auth_required、auth_expired	没有会话，或 Partiful 已将你登出。请在 Chrome 中登录 Partiful，然后运行 partiful-mcp connect。
403	app_permission_denied	只有活动主持人才能执行此操作。
403	scope_denied	服务以只读模式运行，或请求会更改你的 Partiful 账户。
403	target_blocked	Partiful 拒绝了请求或显示了机器人验证。在 Chrome 中打开一次 partiful.com，然后重试。
409	captcha_required	Partiful 要求完成 CAPTCHA。请在 Chrome 中完成验证。
422	invalid_input	参数缺失或错误；消息会指出具体参数。
429	rate_limited	Partiful 正在限制此账户的请求。请等待几分钟。
502	target_error	Partiful 返回了错误，或其网站已更改。请运行 git pull 获取最新工具，或提交问题。

自托管或托管

	此仓库	Cotlet，托管版
工具	相同的 14 个	相同的 14 个
运行方式	在你的电脑上运行，电脑开机时可用	在云端 24/7 运行
Partiful 会话	你的 Chrome、Cookie 和刷新令牌存储在本地文件中	你专属的欧盟云浏览器，配置文件使用 AES-256-GCM 加密
Partiful 更改网站时	修复完成后执行一次 git pull	我们会为你修复，每天测试每个工具
审批	MCP 客户端会逐次调用请求审批	邀请、Text Blasts 和审批会等待你的确认，可按工具切换
兼容对象	你设备上的 MCP 客户端、本地脚本	Claude.ai 和 ChatGPT 连接器、n8n、Make、Zapier，以及任何 HTTP 客户端
适用对象	你本人，仅限非商业用途	团队、企业、代理机构
价格	免费	免费试用 7 天，含 2,000 点数，无需银行卡；之后可一次性购买套餐，5,000 点数起价 $29

在托管版本中，Partiful 调用成功会消耗 25 点数，失败的调用免费；只要云浏览器启用了供 Agent 使用的应用，每天就会消耗 50 点数。完整定价.

常见问题

Partiful 有官方 API 吗？ 没有。Partiful 没有公开 API、开发者文档或 Webhook，帮助中心也没有记录 Zapier 或 Make 的连接方式。访客数据只能通过你手动点击 Export CSV 按钮导出为 CSV 文件后，才能离开 Partiful。详情：cotlet.dev/integrations/partiful-api-mcp-server。

有适用于 Claude、ChatGPT 或 Cursor 的 Partiful MCP 服务吗？ 有，这个服务在你的机器上运行：适用于 Claude Code、Claude Desktop、Cursor 和 Codex 的 partiful-mcp mcp。ChatGPT 和 Claude.ai 连接器需要一个公开的 HTTPS URL，托管版 Partiful MCP 服务可提供此 URL。

我可以将 Partiful 访客名单导出为 CSV 或 Google Sheets 吗？ 可以：python examples/export_guest_list.py --event <id> --out guests.csv 会保存 Export CSV 文件；examples/export_rsvps.py 则为每位访客生成一行，并为每个问卷问题生成一列，方便导入表格。与 Partiful 自带的导出功能一样，这两种方式都不会导出电话号码和电子邮件地址。

它能发送 Text Blasts 吗？ 可以，使用 send_text_blast 向你选择的 RSVP 状态发送。Partiful 每场活动最多允许发送 10 条，但不会告知剩余次数；向 Invited 状态的人员发送群发消息，人数最多只能有 100 人。消息发送后无法编辑或撤回。

可以通过电话号码邀请他人吗？ 不可以。Partiful 只能在其应用中使用电话联系人。invite_guests 可以邀请 list_past_guests 返回的 Partiful 用户，也可以通过电子邮件邀请任何人。

为什么需要我的 Chrome？ 为了读取你的 Partiful 会话，而不需要短信验证码。每次登录时只需使用一次 Chrome，不必每次调用都使用：每小时的令牌续期会直接发送给 Google。

Partiful 将我登出后会怎样？ 调用会因 auth_expired 失败。如果 Chrome 开启了远程调试，服务会在下次调用时读取新的会话（Chrome 提示时点击 Allow）；否则，请在 partiful.com 登录，然后再次运行 partiful-mcp connect。

可以在 VPS 或 Docker 中运行吗？ 技术上可以：先在装有 Chrome 的机器上连接一次，再将 session.json 复制到服务器的 PARTIFUL_MCP_HOME 目录中。这样一来，Partiful 会看到你的会话来自数据中心 IP，这看起来就不太像是你本人。若要始终在线运行，托管版会将你的会话保存在你自己的 Cloud Browser 中，并使用固定 IP。

我的 Partiful 账号会被封禁吗？ 请求会携带 Chrome 的指纹，并且一次只发送一个，就像你亲自点击一样。没人能保证平台永远不会采取措施。请保持正常使用，不要向未主动要求的人发送群发消息或邀请他们。

我可以在工作中或为客户使用吗？ 不可以，许可证仅允许非商业用途。团队、公司或客户项目请使用 Cotlet，或联系 [email protected]。

它是开源的吗？ 源代码是公开的，但许可证并非开源许可证：仅限非商业用途，不得用于商业活动。

工具出错了，或者我需要其他工具。 请提交 issue，并注明工具名称和错误消息。

许可证

PolyForm Noncommercial License 1.0.0。简而言之：

• **允许：**非商业用途：你使用自己的 Partiful 账号满足个人需求，或慈善机构、学校、公共研究机构或政府部门使用。可以修改代码，并按照相同许可证分享。
• **不允许：**任何商业用途，包括经营自己的业务；客户项目；出售或提供本项目，或基于本项目构建的服务。

---

由 Cotlet（@cotletdev）维护。Partiful 是其所有者的商标。本项目为非官方项目，与 Partiful 无关联，也未获得其认可或赞助。