HelloAsso

向助手询问 “我们上个月收了多少钱？”、“Camille Martin 的会员费付了吗？”、“给我晚宴的参会者名单”——就能从财务主管用于对账的同一个 HelloAsso 中获得答案。

> how much did we collect in September, and on what?

  summarize_payments   2026-09 · 214 payments read
                       collected   8 342,00 €   (196 authorized)
                       Membership/adhesion-2026     5 160,00 €   61.9%
                       Event/gala-2026              2 730,00 €   32.7%
                       Donation/dons                  452,00 €    5.4%
                       by means: Card 7 912,00 € · Sepa 430,00 €
                       refunded 60,00 € · 3 refused · 1 contested

> who registered for the gala, with their dietary answers?

  list_form_items      form_url = helloasso.com/associations/les-amis-du-velo/evenements/gala-2026
                       item_states = Processed, Registered · with_details = true
                       87 participants, 3 tiers, custom field "Régime alimentaire"

粘贴 HelloAsso URL，说“上个月”，再提供一个姓名。服务会解析组织、表单、时间段和分页。

为什么选择它

HelloAsso API 提供了简洁的 REST 接口，但直接把它交给大模型，常常会出现一些意料之中的问题：金额单位是分，表单由没人记得的 (type, slug) 组合标识，日期范围采用左闭右开，令牌每 30 分钟过期，而最重要的调用——退款——会直接退回真实款项，且无法撤销。

• 完整 API，不作隐藏。 公共 v5 规范中的全部 36 个路由，各对应一个工具；另有 whoami 和 summarize_payments，因为 API 没有供客户端使用的“我是谁”接口，也没有汇总功能。如果数量减少，测试就会失败。
• 用 URL、词语和时间段，而不是标识符。 每个表单工具都接受表单的公开 URL。表单类型可用英语、法语或 URL 拼写（evenements、adhésions）识别。时间段可用 last month、2026-09、last 30 days 表示。可通过 search 查找人员。
• 金额汇总准确无误。 summarize_payments 会遍历所有分页，并按表单、付款方式和月份拆分实际收款额（Authorized），同时提供分和欧元金额——不会让模型把第一页的金额加起来就当作总额。
• 涉及资金操作时默认拒绝。 refund_payment 和 cancel_order 必须提供 confirm: true 才会运行；拒绝提示会说明金额和付款人，以便用户在充分知情后确认。设置 HELLOASSO_READ_ONLY=1 后，所有写入工具都会被禁用。
• 按 HelloAsso 的要求处理 OAuth。 先使用一次 client_credentials，之后使用 refresh_token——只要刷新可用，就绝不申请新的授权，这是 API 的要求。服务端撤销令牌后，服务会自动续期。
• 内容适合模型读取。 全部 38 个工具都有带架构的结构化输出和注释；提供四个提示词，在操作资金前暂停并询问；服务说明则会提前强调：金额单位是分。

安装

# macOS on Apple silicon; swap the target for x86_64-apple-darwin,
# x86_64-unknown-linux-gnu or aarch64-unknown-linux-gnu
V=v0.1.1 T=aarch64-apple-darwin
curl -LO https://github.com/edouard-claude/helloasso-mcp/releases/download/$V/mcp-helloasso-$V-$T.tar.gz
tar xzf mcp-helloasso-$V-$T.tar.gz
sudo mv mcp-helloasso-$V-$T/mcp-helloasso /usr/local/bin/

git clone https://github.com/edouard-claude/helloasso-mcp
cd helloasso-mcp
cargo build --release
# the binary is at target/release/mcp-helloasso

cargo install --git https://github.com/edouard-claude/helloasso-mcp

docker run --rm -i \
  -e HELLOASSO_CLIENT_ID=… -e HELLOASSO_CLIENT_SECRET=… \
  ghcr.io/edouard-claude/helloasso-mcp:latest

获取 API 凭据

在你所在协会的 HelloAsso 管理后台中，依次选择：我的账户 → 集成与 API （Mon compte → Intégrations et API）。你会获得一个客户端 ID和一个客户端密钥， 并拥有适用于你所在组织的 AccessPublicData、AccessTransactions 和 Checkout 权限。 合作伙伴可向 HelloAsso 合作团队获取这些凭据。

然后，在将客户端连接到服务之前，先检查配置：

HELLOASSO_CLIENT_ID=… HELLOASSO_CLIENT_SECRET=… mcp-helloasso --check

environment  production
base url     https://api.helloasso.com/v5
toolsets     organization, forms, sales, checkout, directory, partner
read only    false
tools        38
token        ok
reachable    1 organization(s)
             Les Amis du Vélo (les-amis-du-velo) as OrganizationAdmin
organization Les Amis du Vélo (les-amis-du-velo)

ready.

配置

使用哪个组织。 协会的客户端只能访问一个组织，服务会自动查找该组织。合作伙伴的客户端若可访问多个组织，则会收到候选组织列表；请设置 HELLOASSO_ORGANIZATION，或在每次调用时传入 organization。如果变量格式错误，二进制文件会拒绝启动，并指出有问题的变量。

连接客户端

claude mcp add helloasso --scope user \
  --env HELLOASSO_CLIENT_ID=… \
  --env HELLOASSO_CLIENT_SECRET=… \
  -- /absolute/path/to/mcp-helloasso

{
  "mcpServers": {
    "helloasso": {
      "command": "/absolute/path/to/mcp-helloasso",
      "env": {
        "HELLOASSO_CLIENT_ID": "…",
        "HELLOASSO_CLIENT_SECRET": "…",
        "HELLOASSO_READ_ONLY": "1"
      }
    }
  }
}

然后询问 “你连接的是哪个 HelloAsso 组织？”。whoami 应会返回你所在协会的名称。

工具

38 个工具，分为六个工具集，涵盖公共 v5 规范中的 36 个路由。 HELLOASSO_TOOLSETS 用于选择要注册的工具；HELLOASSO_READ_ONLY=1 则仅保留声明为只读的工具。

sales — 订单、项目、付款及财务主管视图

forms — 活动

checkout — 付款链接

organization — 组织及相关信息

directory — HelloAsso 公共目录

partner — 面向 HelloAsso 合作伙伴

资源和提示词

三个资源和两个模板，供更倾向于在调用函数时附加上下文的客户端使用：

四个提示词可驱动协会实际使用的工作流：

• treasury_report — 总额、各活动的细分、平均值、退款以及值得关注之处，使用法语数字格式。不写入任何内容。
• find_person — 某个人进行的所有操作：会员资格、门票、付款以及待处理事项。不写入任何内容。
• attendee_list — 某个表单的所有参与者及其回答，逐页查看到最后一页，并与表单统计数据核对。不写入任何内容。
• refund_request — 查找付款、检查资格、提出建议、停止并等待，然后退款并重新读取记录。

HelloAsso 的实际运行方式

以下内容均经过实时 API 验证，已由你处理，并记录在此，因为下一个集成 HelloAsso 的人也会遇到同样的问题。

安全性

读取资金账目属于敏感操作；修改账目则更为敏感。默认设置倾向于谨慎处理。

• 资金操作默认拒绝。 refund_payment、cancel_order、删除表单和移除 webhook 均会在缺少 confirm: true 时拒绝操作。拒绝退款时，会先读取付款信息，并提示 "付款 67890（Camille Martin 支付的 25.00 €，状态为 Authorized）将被全额退款"，让操作者确认实际看到的信息。这四个工具均标注了 destructiveHint。
• 只读限制是结构性实现的。 HELLOASSO_READ_ONLY=1 会移除所有未标注 readOnlyHint 的路由，无需维护一份需保持同步的保留名称列表，因此新写入工具也会自然排除在外。测试对此有断言。
• 发送 HTTP 请求前会检查输入。 slug 不能越出其路径片段，结账各项金额之和必须等于总额，URL 必须以 https:// 开头，ID 必须为正数。
• 绝不泄露密钥。 密钥在 Debug 中会被遮蔽，只会发送到令牌端点，绝不会序列化到工具回答或日志行中；whoami 只显示客户端 ID 的前八个字符，不显示密钥。
• 不会通过 HTTP 写入磁盘。 通过 HTTP 访问服务时，export_cash_out 的 save_to 会被拒绝。
• 提示词会先征求同意。 唯一可能转移资金的提示词会暂停操作，等待明确批准，并要求提供 MFA 验证码，而不是自行猜测。

改为通过 HTTP 运行

mcp-helloasso --http 127.0.0.1:8080
# MCP at http://127.0.0.1:8080/mcp, health at /healthz

在回环地址之外，如果未设置 HELLOASSO_HTTP_TOKEN，服务将拒绝启动：一个 API 客户端就代表一个身份，而开放的端点就等于为某个协会的款项敞开大门。设置令牌后， 每个发往 /mcp 的请求都需要携带 Authorization: Bearer <token>；/healthz 则保持开放，供探测使用。所有会话共享一个 OAuth 令牌。

docker run -d --name mcp-helloasso -p 8080:8080 \
  -e HELLOASSO_CLIENT_ID=… \
  -e HELLOASSO_CLIENT_SECRET=… \
  -e HELLOASSO_HTTP_BIND=0.0.0.0:8080 \
  -e HELLOASSO_HTTP_TOKEN="$(openssl rand -hex 32)" \
  mcp-helloasso

在前面配置 TLS。该进程使用纯 HTTP 通信，并不会假装使用其他协议。

验证

cargo test                                   # 79 tests
cargo clippy --all-targets -- -D warnings
cargo fmt --all --check
mcp-helloasso --list-tools                   # the surface, as registered
mcp-helloasso --check                        # the configuration, against the live API

测试套件包含对协议本身的测试：tests/mcp_stdio.rs 会启动实际二进制文件， 通过其 stdin 发送 JSON-RPC，并断言返回内容——包括握手、全部 38 个工具及其架构、 通过 URL 指定的表单、转换为日期的周期、仅统计已收款项的摘要、未经确认时拒绝退款、 携带 MFA 标头发送退款，以及只读模式。tests/api_contract.rs 使用模拟的 HelloAsso 测试令牌生命周期、重试和错误封装；tests/mcp_http.rs 则检查 HTTP 传输和 Bearer 令牌校验。

src/
├── client.rs      REST over HTTP: OAuth2 lifecycle, retries, the three error envelopes
├── config.rs      the environment, validated once, with the secret redacted
├── resolve.rs     URLs, slugs and form types, and the refusal to guess
├── dates.rs       today, last month, 2026-09, last 30 days
├── tools/         one module per toolset, one function per route
├── resources.rs   three URIs and two templates
├── prompts.rs     four workflows that ask before touching money
└── server.rs      capabilities, instructions, and the glue

发布

在 Cargo.toml 中更新 version，在 CHANGELOG.md 中添加对应版本章节，然后 推送一个标签：

git tag v0.1.1 && git push origin v0.1.1

发布工作流会检查标签是否与 Cargo.toml 和变更日志一致，构建五个二进制文件及其校验和， 推送 ghcr.io/edouard-claude/helloasso-mcp，并使用变更日志中的对应章节作为说明发布 GitHub 版本。

贡献

欢迎提交问题和拉取请求。当 cargo test、 cargo clippy --all-targets -- -D warnings 和 cargo fmt --all --check 均通过，并且 新工具包含描述、注解和输出架构时，这项变更就可以提交——否则，三个测试会告诉你问题所在。

许可证

MIT——详见 LICENSE。与 HelloAsso 无关联；HelloAsso 是其所有者的商标。