HelloAsso

mcp-helloasso

Your association's HelloAsso, answered by asking.

A single Rust binary that puts the whole HelloAsso v5 API — memberships, tickets, donations, payments, refunds, checkouts — in front of any MCP client.

🇫🇷 Serveur MCP pour HelloAsso : adhérents, billetterie, dons, paiements et remboursements, interrogés en langage naturel depuis Claude, Cursor ou tout client MCP.

Ask your assistant "how much did we collect last month?", "is Camille Martin's membership paid?", "give me the attendee list of the gala" — and get the answer from the same HelloAsso your treasurer reconciles against.

> 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"

Paste a HelloAsso URL, say last month, name a person. The server resolves the organization, the form, the period and the pagination.

Why

HelloAsso's API is a clean REST surface, but handing it raw to a language model goes wrong in predictable ways: amounts are cents, a form is a (type, slug) pair nobody remembers, date ranges are half-open, tokens expire every 30 minutes, and the one call that matters most — a refund — sends real money back with no undo.

• The whole API, nothing hidden. All 36 routes of the public v5 spec, one tool each, plus whoami and summarize_payments, which exist because the API has no "who am I" for a client and no aggregate. A test fails if that count ever drops.
• URLs, words and periods, not identifiers. Every form tool takes the form's public URL. Form types read in English, French or URL spelling (evenements, adhésions). Periods read last month, 2026-09, last 30 days. Persons are found with search.
• Money that adds up. summarize_payments walks every page and splits what was actually collected (Authorized) per form, payment means and month, in cents and euros — no model adding up page one and calling it a total.
• Fail-closed where money moves. refund_payment and cancel_order refuse to run without confirm: true, and the refusal states the amount and the payer so the confirmation is an informed one. HELLOASSO_READ_ONLY=1 withholds every write tool.
• OAuth handled the way HelloAsso asks. client_credentials once, then refresh_token — never a new grant while a refresh works, as the API requires. A token revoked server-side is renewed transparently.
• Written for a model to read. Structured output with schemas on all 38 tools, annotations on every one, four prompts that stop and ask before touching money, and server instructions that say up front: amounts are cents.

Install

Prebuilt binary (macOS, Linux, Windows)

Download the archive for your platform from the latest release, check it against its .sha256, and put mcp-helloasso on your PATH:

# 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/

Windows: take the x86_64-pc-windows-msvc.zip archive.

From source (any platform with Rust 1.88+)

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

With cargo install

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

With Docker

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

Or build it yourself with docker build -t mcp-helloasso ..

The server is listed in the official MCP registry as io.github.edouard-claude/helloasso-mcp, so registry-aware clients offer it directly with the variables to fill in.

The image runs unprivileged and speaks stdio by default; add --http for the HTTP transport. See Run it over HTTP instead.

Get API credentials

In the HelloAsso back office of your association: My account → Integrations and API (Mon compte → Intégrations et API). You get a client id and a client secret, with the AccessPublicData, AccessTransactions and Checkout privileges, scoped to your organization. Partners get theirs from HelloAsso's partnership team.

Then check the wiring before pointing a client at it:

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.

Configure

| Variable | Required | Default | What it is | |---|:-:|---|---| | HELLOASSO_CLIENT_ID | yes | | The API client id | | HELLOASSO_CLIENT_SECRET | yes | | Its secret | | HELLOASSO_CLIENT_SECRET_FILE | | | A file holding the secret instead, for Docker secrets | | HELLOASSO_ACCESS_TOKEN | | | Instead of a client: a ready-made bearer token, used as is | | HELLOASSO_ENVIRONMENT | | production | sandbox targets api.helloasso-sandbox.com | | HELLOASSO_ORGANIZATION | | | The organization slug tools default to | | HELLOASSO_TOOLSETS | | all | organization,forms,sales,checkout,directory,partner | | HELLOASSO_READ_ONLY | | 0 | 1 withholds every write tool | | HELLOASSO_TIMEOUT_SECS | | 30 | Per-request timeout | | HELLOASSO_MAX_RETRIES | | 3 | Retries on 429 and transient 5xx | | HELLOASSO_BASE_URL | | per environment | API root override | | HELLOASSO_TOKEN_URL | | per environment | Token endpoint override | | HELLOASSO_HTTP_BIND | | | Listen address for the HTTP transport | | HELLOASSO_HTTP_TOKEN | | | Bearer token the HTTP transport requires | | HELLOASSO_LOG | | info | warn, debug, mcp_helloasso=debug… |

Which organization. An association's client reaches exactly one organization, and the server finds it on its own. A partner client reaching several gets the list back as candidates; set HELLOASSO_ORGANIZATION or pass organization per call. The binary refuses to start on a malformed variable and names the one at fault.

Connect a client

Claude Code

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

Claude Desktop

claude_desktop_config.json:

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

Start read-only; lift it once you trust the setup.

Cursor, Windsurf, Zed, and other stdio clients

Same shape: one command pointing at the binary, the credentials in env. The server speaks the stdio transport and prints nothing but protocol on stdout — logs go to stderr.

Any client, over HTTP

Point it at http://127.0.0.1:8080/mcp after starting the server with --http 127.0.0.1:8080. See below.

Then ask "which HelloAsso organization are you connected to?". whoami should answer with your association's name.

Tools

38 tools in six toolsets, covering the 36 routes of the public v5 spec. HELLOASSO_TOOLSETS picks which ones are registered; HELLOASSO_READ_ONLY=1 keeps only the ones that declare themselves read-only.

sales — orders, items, payments, the treasurer's view

forms — the campaigns

checkout — payment links

organization — who and what

directory — HelloAsso's public directory

partner — for HelloAsso partners

Resources and prompts

Three resources and two templates, for clients that prefer attaching context to calling a function:

Four prompts drive the workflows associations actually run:

• treasury_report — totals, per-campaign split, means, refunds and what stands out, in French number formatting. Writes nothing.
• find_person — everything one person did: memberships, tickets, payments, what is pending. Writes nothing.
• attendee_list — every participant of a form with their answers, walked to the last page and checked against the form's statistics. Writes nothing.
• refund_request — find the payment, check eligibility, propose, stop and wait, then refund and read it back.

HelloAsso, as it actually behaves

Everything below was checked against the live API, is handled for you, and is written down because the next person integrating HelloAsso will hit the same walls.

Safety

Reading a treasury is sensitive; changing it is more so. The defaults lean careful.

• Money is fail-closed. refund_payment, cancel_order, deleting a form and removing a webhook refuse without confirm: true. A refused refund reads the payment first and says "payment 67890 (25.00 € by Camille Martin, Authorized) would be refunded in full", so the person confirms what they actually see. All four are annotated destructiveHint.
• Read-only is structural. HELLOASSO_READ_ONLY=1 drops every route that does not annotate itself readOnlyHint — not a list of names to keep in sync, so a new write tool is excluded by construction. A test asserts it.
• Inputs are checked before HTTP. Slugs cannot escape their path segment, checkout terms must add up to the total, URLs must be https://, ids must be positive.
• The secret never leaks. It is redacted in Debug, sent only to the token endpoint, and never serialized into a tool answer or a log line; whoami shows the first eight characters of the client id and nothing of the secret.
• No disk writes over HTTP. export_cash_out's save_to is refused when the server is reached over HTTP.
• The prompts ask first. The only prompt that can move money stops for explicit approval, and asks for the MFA code rather than guessing.

Run it over HTTP instead

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

Off loopback, the server refuses to start without HELLOASSO_HTTP_TOKEN: one API client means one identity, and an open endpoint is an open door to an association's payments. With the token set, every request to /mcp needs Authorization: Bearer <token>; /healthz stays open for probes. All sessions share one OAuth token.

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

Put TLS in front of it. The process speaks plain HTTP and does not pretend otherwise.

Verify

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

The suite includes the protocol itself: tests/mcp_stdio.rs spawns the real binary, speaks JSON-RPC to its stdin and asserts on what comes back — the handshake, all 38 tools with their schemas, a form named by URL, a period turned into dates, a summary that only counts collected money, a refund refused without confirmation and sent with its MFA header with it, read-only mode. tests/api_contract.rs holds the token lifecycle, the retries and the error envelopes against a fake HelloAsso, and tests/mcp_http.rs checks the HTTP transport and its bearer guard.

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

Releasing

Bump version in Cargo.toml, add its section to CHANGELOG.md, then push a tag:

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

The release workflow checks the tag against Cargo.toml and the changelog, builds the five binaries with their checksums, pushes ghcr.io/edouard-claude/helloasso-mcp, and publishes the GitHub release with the changelog section as notes.

Contributing

Issues and pull requests welcome. A change is ready when cargo test, cargo clippy --all-targets -- -D warnings and cargo fmt --all --check pass, and when a new tool carries a description, an annotation and an output schema — three tests will tell you if it does not.

License

MIT — see LICENSE. Not affiliated with HelloAsso; HelloAsso is a trademark of its owner.