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インターフェースですが、そのままLLMに渡すと、よくある問題が起きます。金額はセント単位であり、フォームは誰も覚えていない (タイプ、スラッグ) の組み合わせで、日付範囲は片側が開いており、トークンは30分ごとに期限切れになります。そして最も重要な呼び出しである返金は、取り消しできないまま実際のお金を返します。

• API全体を網羅し、隠し機能はありません。 公開v5仕様の全36ルートにそれぞれ1つのツールを用意し、さらに whoami と summarize_payments を追加しています。これらは、APIにクライアント向けの「自分は誰か」という機能も集計機能もないために用意しました。この数が減るとテストが失敗します。
• 識別子ではなく、URL、言葉、期間で操作できます。 すべてのフォームツールにはフォームの公開URLを渡します。フォームタイプは英語、フランス語、URL表記（evenements、adhésions）で指定できます。期間は last month、2026-09、last 30 days で指定できます。人物は search で検索します。
• 金額を正しく集計できます。 summarize_payments はすべてのページをたどり、フォーム、支払い方法、月ごとに、実際に 集金された金額（Authorized）をセントとユーロで集計します。モデルが1ページ目の金額を合計して総額とすることはありません。
• 資金を動かす処理は、確認がなければ実行しません。 refund_payment と cancel_order は confirm: true がなければ実行を拒否し、その際に金額と支払者を明示するため、確認に必要な情報を得られます。HELLOASSO_READ_ONLY=1 を設定すると、すべての書き込みツールが利用できなくなります。
• HelloAssoの指定どおりにOAuthを処理します。 最初に client_credentials を使い、その後は refresh_token を使います。APIの要件に従い、トークンの更新が機能する間は新しい認可を取得しません。サーバー側でトークンが取り消されても、透過的に更新されます。
• モデルが読み取りやすい設計です。 38個すべてのツールにスキーマ付きの構造化出力とアノテーションを用意しています。資金を扱う前に確認を求めるプロンプトが4つあり、サーバー指示には冒頭で金額がセント単位であることを明記しています。

インストール

# 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管理画面で、My account → Integrations and API （Mon compte → Intégrations et API）を開きます。組織を対象範囲として、AccessPublicData、AccessTransactions、Checkoutの権限が付与されたクライアントIDとクライアントシークレットを取得できます。パートナーは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.

設定

組織の指定。 団体のクライアントがアクセスできる組織は1つだけで、サーバーが自動的に特定します。複数の組織にアクセスできるパートナークライアントの場合、候補の一覧が返されます。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が所属団体の名前を返すはずです。

ツール

6つのツールセットに38個のツールがあり、 公開 v5 仕様の36個のルートをカバーしています。 HELLOASSO_TOOLSETSで登録するツールセットを選択できます。HELLOASSO_READ_ONLY=1を設定すると、読み取り専用を宣言しているツールのみが残ります。

sales — 注文、商品、支払い、会計担当者向けの情報

forms — キャンペーン

checkout — 支払いリンク

organization — 組織とその情報

directory — HelloAsso の公開ディレクトリ

partner — HelloAsso パートナー向け

リソースとプロンプト

関数の呼び出しよりも、コンテキストの添付を好むクライアント向けに、3 つのリソースと 2 つのテンプレートを用意しています。

団体が実際に実行するワークフローを、4 つのプロンプトで進めます。

• treasury_report — 合計、キャンペーン別の内訳、平均、返金、注目すべき点を、フランス式の数値表記でまとめます。何も書き込みません。
• find_person — ある人物が行ったすべてのことを確認します。会員登録、チケット、支払い、保留中の項目を調べます。何も書き込みません。
• attendee_list — フォームのすべての参加者と回答を一覧にし、最後のページまで確認してフォームの統計と照合します。何も書き込みません。
• refund_request — 支払いを見つけ、返金の適格性を確認し、提案します。その後、停止して待機し、返金して結果を読み戻します。

実際の動作に基づく HelloAsso

以下はすべて実際の API で確認済みで、サーバーが処理し、次に HelloAsso を統合する人も同じ問題に直面するため、記録しています。

安全性

財務情報の閲覧は慎重さが必要ですが、変更にはそれ以上の注意が必要です。デフォルトでは慎重な動作を優先します。

• 金銭に関わる操作は、確認できなければ拒否します。 refund_payment、cancel_order、フォームの削除、Webhook の削除は、confirm: true がなければ拒否します。返金を拒否する際は、まず支払いを読み込み、「支払い 67890（Camille Martin による 25.00 €、承認済み）は全額返金されます」と表示するため、利用者は実際に表示された内容を確認できます。これら4つには destructiveHint の注釈があります。
• 読み取り専用は構造的に保証されます。 HELLOASSO_READ_ONLY=1 を設定すると、readOnlyHint の注釈がないルートはすべて除外されます。同期が必要な名前のリストではないため、新しい書き込みツールも構造上除外されます。これを確認するテストがあります。
• HTTP 通信の前に入力を検証します。 スラッグでパスセグメントの外に出ることはできません。チェックアウトの内訳は合計金額と一致する必要があり、URL は https:// で始まり、ID は正の値でなければなりません。
• シークレットが漏れることはありません。 Debug ではマスキングされ、トークンエンドポイントにのみ送信され、ツールの回答やログ行にシリアライズされることはありません。whoami にはクライアント ID の先頭8文字だけが表示され、シークレットは一切表示されません。
• 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 クライアントは 1 つ、つまりアイデンティティも 1 つです。公開されたエンドポイントは、団体の決済への開かれた入口になります。トークンを設定すると、/mcp へのすべてのリクエストに Authorization: Bearer <token> が必要になります。プローブ用に /healthz は公開されたままです。すべてのセッションで 1 つの 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 は実際のバイナリを起動し、その標準入力に JSON-RPC を送り、返される内容を検証します。ハンドシェイク、スキーマを含む 38 個すべてのツール、URL で指定されたフォーム、期間から変換された日付、回収済みの金額だけを集計するサマリー、確認なしでは拒否され、MFA ヘッダーを付けると送信される返金、読み取り専用モードが対象です。tests/api_contract.rs では、偽の HelloAsso に対するトークンのライフサイクル、再試行、エラーエンベロープを検証し、tests/mcp_http.rs では HTTP トランスポートとベアラー認証ガードを確認します。

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 と変更履歴に一致することを確認し、チェックサム付きの 5 つのバイナリをビルドして、ghcr.io/edouard-claude/helloasso-mcp にプッシュします。また、変更履歴の該当セクションをリリースノートとして GitHub リリースを公開します。

コントリビューション

Issue とプルリクエストを歓迎します。cargo test、cargo clippy --all-targets -- -D warnings、cargo fmt --all --check が成功し、新しいツールに説明、アノテーション、出力スキーマが含まれていれば変更の準備は完了です。これらが含まれていない場合は、3 つのテストでわかります。

ライセンス

MIT — LICENSE を参照してください。HelloAsso とは提携していません。HelloAsso はその所有者の商標です。