helloasso-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@helloasso-mcp show me the latest payments for my association"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
helloasso-mcp
Read-only Model Context Protocol server (stdio) for the HelloAsso API v5. It lets an MCP client (Claude Desktop, Cursor, any agent supporting stdio MCP servers...) read an association's HelloAsso data: organization, forms/campaigns (memberships, events, donations, shops...), orders, payments and items (members, participants, with custom fields).
Read-only by design: the server only issues GET requests. It never creates checkouts,
refunds, cancels orders or edits forms.
Tools
Tool | Description |
| Public details of an organization. |
| Organizations the API client has rights on (find your slug). |
| Form types for which the organization has at least one form. |
| List forms/campaigns, filter by type ( |
| Public details of one form (tiers/prices, custom fields, dates...). |
| Statistics of one form. |
| Orders of the organization or of one form, with date range / search. |
| Payments of the organization or of one form, with date range, states, sorting. |
| Items of the organization or of one form, e.g. members of a membership campaign, with custom fields ( |
| One order by id. |
| One payment by id. |
| One item by id, with custom fields. |
Notes:
Every organization-scoped tool accepts an optional
orgSlug; it defaults toHELLOASSO_ORG_SLUG.List tools give
formType+formSlugto restrict to a single form.Pagination: results contain
pagination(pageIndex,pageSize,totalCount,totalPages,continuationToken). PasscontinuationTokenback to get the next page.pageSizeis limited to 100 here.Dates (
frominclusive,toexclusive) are ISO 8601:2026-01-01or2026-01-01T00:00:00Z.Amounts returned by HelloAsso are in cents.
Output is compact JSON (null / empty values removed).
Related MCP server: mysql-mcp-server-all
1. Get API credentials
You need an API client (a Client ID and a Client Secret) from the association's HelloAsso back-office. You must be an administrator of the association.
Sign in to your association's HelloAsso back-office.
Open Mon compte → Intégrations et API.
Click Générer ma clé API if no key exists yet.
Copy the Client ID and the Client Secret.
Your organization slug is the last part of your public page URL:
https://www.helloasso.com/associations/<slug> (for example my-association).
For testing, create a free test organization on https://www.helloasso-sandbox.com and generate
a key there: sandbox keys only work with HELLOASSO_ENV=sandbox.
⚠️ Treat the Client Secret like a password. An association API client also has the
Checkoutprivilege and can refund payments through the API. This server does not use those capabilities, but the key itself allows them: never commit it, paste it in a chat or share it.
2. Install and build
Requires Node.js 20+.
git clone https://github.com/NicolasMassart/helloasso-mcp.git
cd helloasso-mcp
npm install # also builds (prepare script)
npm run build # if needed
npm test3. Configuration (environment variables)
Variable | Required | Description |
| yes | API Client ID. |
| yes | API Client Secret. |
| recommended | Default organization slug, e.g. |
| no |
|
| Token URL | API base URL |
|
|
|
|
|
|
The server starts even without credentials (tools then return a clear error), so you can check that your MCP client sees it before configuring the keys.
4. Add it to an MCP client
Stdio command: node /absolute/path/to/helloasso-mcp/dist/index.js
Generic configuration (Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json, ...):
{
"mcpServers": {
"helloasso": {
"command": "node",
"args": ["/absolute/path/to/helloasso-mcp/dist/index.js"],
"env": {
"HELLOASSO_CLIENT_ID": "<your client id>",
"HELLOASSO_CLIENT_SECRET": "<your client secret>",
"HELLOASSO_ORG_SLUG": "my-association",
"HELLOASSO_ENV": "production"
}
}
}
}You can also run it with npx /absolute/path/to/helloasso-mcp (after npm install in that folder).
Quick check without any client (lists the tools, makes no HelloAsso call):
npm run smokeor with the MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js.
Authentication and limits
OAuth2
client_credentialson the token URL; the access token (30 min) is cached in memory and renewed with therefresh_token(valid 30 days), as HelloAsso requires. Client credentials are only used again if the refresh token is missing, expired or rejected.The token endpoint is rate limited by HelloAsso (10 calls / 10 s, 20 / 10 min, 50 / hour). The cache lives in the server process, so each new process authenticates once.
On
401the token is renewed once and the request retried.403usually means the API client lacks the role/privilege for that route (transactions needOrganizationAdminorFormAdminandAccessTransactions) or that the slug is not the client's own organization.429errors report theRetry-Afterdelay when HelloAsso sends one.Secrets are never logged; logs go to stderr only (stdout is the MCP channel).
Development
npm test # vitest, fetch is mocked: no network, no credentials needed
npm run typecheck
npm run build
npm run smoke # starts dist/index.js over stdio and calls tools/listEndpoints and enums follow the official OpenAPI specification: https://github.com/HelloAsso/helloasso-open-api.
License
MIT
Available Tools
12 toolshelloasso_get_formGet formARead-onlyIdempotent
Public details of one form: title, dates, tiers (prices), custom fields, state, URL.
Inputs: formSlug (required), formType (required), orgSlug.
helloasso_get_form_statsGet form statisticsBRead-onlyIdempotent
Statistics of one form (amounts collected, number of orders/items...).
Inputs: formSlug (required), formType (required), orgSlug.
helloasso_get_itemGet itemARead-onlyIdempotent
Detailed item (one membership, ticket, donation...) by id, with custom fields.
Inputs: itemId (required), withDetails.
helloasso_get_orderGet orderARead-onlyIdempotent
Detailed order by id: payer, items, payments, amounts.
Inputs: orderId (required), withFormData.
helloasso_get_organizationGet organizationARead-onlyIdempotent
Public details of a HelloAsso organization (name, description, address, logo, URLs...).
Inputs: orgSlug.
helloasso_get_paymentGet paymentARead-onlyIdempotent
Detailed payment by id: amount, state, payer, order, refund operations.
Inputs: paymentId (required).
helloasso_list_formsList forms / campaignsARead-onlyIdempotent
List the organization forms (campaigns): memberships, events, donations, shops, crowdfunding, payment forms. Newest first, paginated.
Inputs: states, orgSlug, pageSize, formTypes, +2 more.
helloasso_list_form_typesList form typesBRead-onlyIdempotent
Form (campaign) types for which the organization has at least one form.
Inputs: states, orgSlug.
helloasso_list_itemsList items (members, tickets, donations...)BRead-onlyIdempotent
List items sold by the organization or by one form (formType + formSlug): e.g. the members of a membership campaign or the participants of an event, with custom fields answers.
Inputs: to, from, orgSlug, formSlug, +11 more.
helloasso_list_my_organizationsList my organizationsARead-onlyIdempotent
Organizations the API client has rights on (useful to find the organization slug).
Inputs: no named parameters.
helloasso_list_ordersList ordersARead-onlyIdempotent
List orders of the organization, or of one form when formType + formSlug are given. Supports date range, search and pagination.
Inputs: to, from, orgSlug, formSlug, +8 more.
helloasso_list_paymentsList paymentsBRead-onlyIdempotent
List payments of the organization, or of one form when formType + formSlug are given. Supports date range, payment states, search, sorting and pagination.
Inputs: to, from, states, orgSlug, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource+action: organizations, form types, forms, form stats, items, orders, payments each have clear list/get boundaries. The list-vs-get distinction is unambiguous, and helloasso_list_my_organizations vs helloasso_get_organization is disambiguated by the descriptions (access rights vs public details).
Every tool follows the same helloasso_<verb>_<noun> pattern in consistent snake_case, with predictable list/get pairs. No mixing of conventions or vague verbs.
12 tools is well within the ideal range and each earns its place: list/get coverage across orgs, forms, items, orders, payments, plus form-types and stats helpers. No redundancy.
Full read/list lifecycle coverage for the domain (orgs, forms, items, orders, payments, stats) with no obvious list/get dead ends. Minor gaps: no create/update/delete or refund-initiation tool, though the server appears intentionally read-only and get_payment references refund operations it cannot act on.
Maintenance
Related MCP Connectors
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Public read-only MCP server for HODLXXI agent identity, trust, receipts, and verification.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA read-only MCP server for accessing Mobilize public API data, including organizations, events, and enums.-
- AlicenseAqualityDmaintenanceA read-only MySQL MCP server supporting stdio, SSE, and Streamable HTTP transports, enabling secure querying and schema inspection of MySQL databases from MCP clients.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to read Sierra Chart study outputs, chart discovery, and study metadata/history via read-only tools over Streamable HTTP or stdio.MIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP clients to browse and read files, folders, photo albums, and metadata in the user's cloud drive through a read-only stdio server, including folder listing, full-text search, glob-based finding, file reading, item stats, and storage quota reporting.MIT