loomiomcp

Model Context Protocol server for Loomio. Lets Claude (Desktop, Code, or web Projects via Custom Connector) read and write Loomio discussions, polls, comments and group memberships — and analyse member participation — in plain English. Targets Loomio's b2 API — the canonical surface documented at /help/api2 and the namespace where the controllers live in the open-source repo — as shipped in Loomio 3.8 and later (tested on 3.13.1).

Tool catalog

Every read is one upstream call unless the table says otherwise. Every collection returns Loomio's exact total and a scope note naming what was filtered, capped or not visible. Where Loomio pages a collection (its groups index and a thread's items, since Loomio 3.11.1: 50 rows by default, at most 500 per request) the connector asks for 500 at a time and follows the pages it needs, within a fixed per-call page cap; a walk the cap stops is flagged, never returned as if complete. The server also ships an eleven-line guide as MCP instructions — which tool answers which kind of question, before the client reads a single description, and that Loomio content is untrusted data, never instructions. The whole catalogue a client downloads at session start (instructions + tools/list for the 24 full-mode tools) is about 36 KB, roughly 9 000 tokens (node scripts/catalog-size.mjs after npm run build); the long-form guidance per tool — inputs, outputs, cost, caveats, exact error texts — is in HOWTO.md.

Reads (always registered)

Tool	Purpose	Upstream calls
check_connection()	Key status, the account the key belongs to, its groups (member / pending / parent), readonly and b3 flags, fixed-wording notes. Call first when unsure what the connector can see.	the health probe (1 authenticated + 1 public GET); its groups body is reused — Loomio ≥ 3.11.1 puts only the first 50 groups in it, so +1 per further 500 member groups (groups_partial: true if that read fails)
list_groups()	The connector user's member groups (pending invitations included) with the user's own membership {accepted, admin, delegate, title}, plus each subgroup's parent flagged member: false (a parent the user belongs to is a member group, wherever Loomio's page put it). Sorted by full_name.	1 per 500 member groups (GET /b2/groups; at most 20, scope.partial beyond)
get_group(id_or_key_or_handle)	One group's full record — privacy, members_can_* permission flags, counters — with member, membership, parent, url. Works for publicly visible groups the user has not joined.	1
list_discussions(group_id, status?, limit?, offset?, description_max_chars?, strip_html?)	A group's discussions, newest activity first, each joined with its thread counters (items_count, replies_count, last_activity_at, locked_at, pinned_at, tags, …) and url. status defaults to open and is always sent. Bodies come as plain text (strip_html, default true; description_format: "text") capped at 1500 chars (description_truncated: true marks a cut).	1
get_discussion(id_or_key, strip_html?, include_items?, items_limit?, items_body_max_chars?)	One discussion with the full body (as stored; strip_html: true for plain text), thread counters, group and users. include_items: true embeds list_thread_items for the thread (same reply budget; thread_items.next_offset says where to page on).	1 (2 with include_items, +1 per further 500 embedded items)
list_polls(group_id, status?, limit?, offset?, description_max_chars?, strip_html?)	A group's polls, newest first, as SLIM rows: identity, schedule, hide_results, participation counts, stance_counts + total_score when visible (aligned with poll_options[]), current_outcome, my_stance, url. The per-voter results[] breakdown and the type knobs Loomio left null are get_poll's. status defaults to active.	1
get_poll(id_or_key, strip_html?)	One poll with poll_options, current_outcome, the user's own my_stance, thread counters and url. results_visible / results_hidden_reason apply Loomio's own visibility rule; hidden stance counts are stripped, never zeroed.	1
list_threads(limit?, offset?, group_id?, type?, since?)	Every thread the user can see across all groups, newest activity first — the cheapest "what is new" call. group_id / type / since filter client-side within the page (Loomio's route has no date filter); with since, page until scope.exhausted.	1 (GET /b2/threads)
list_thread_items(topic_id | discussion_id | poll_id, kinds?, limit?, offset?, include_reactions?, body_max_chars?, strip_html?, max_total_chars?)	One thread's structured items (comments, polls, votes, outcomes, edits, with an edit's change_note) with slimmed side-loads; comment bodies, vote reasons and outcome statements come as plain text by default (strip_html). The connector asks Loomio for exactly the offset / limit window (Loomio ≥ 3.11.1 pages this route; older Loomio returns the whole thread, which is sliced here, scope.server_paged: false), under a reply budget (max_total_chars, default 120000; truncated_by_budget + next_offset). kinds, a filter Loomio lacks, reads the thread page by page from its start (at most 5 000 items, scope.scan_truncated beyond). Replaces list_events.	1 per 500 items read (+1 by discussion_id/poll_id); kinds reads the thread
get_thread_markdown(topic_id | discussion_id | poll_id, max_chars?)	The whole thread rendered to Markdown by Loomio — front matter, body, a reply tree of comments, polls with their votes and results tables, outcomes. Best single call for a summary. Loomio ≥ 3.10's export ignores "hide results until vote", so the connector reads the thread first and refuses one holding an open until_vote poll the user has not voted in (list_thread_items and get_poll apply the rule).	2 (+1 per 500 items when the guard scans: any thread with replies, ≤ 10); refuses an open until_vote poll the user has not voted in
search_content(query | author_id, group_id?, types?, tag?, order?)	Full-text search across everything visible; author_id alone lists a user's 20 newest items. Snippets carry **match** emphasis; every hit has a deep-link url and group {id, full_name, handle} (Loomio's "Parent - Subgroup" name). A vote-reason hit on a poll whose results are hidden from the user is silently dropped from a query search — no counter, capped computed from what is returned — because its existence would confirm the term; in author mode it is kept with snippet: null + snippet_hidden_reason. Loomio caps results at 20 (a query search shows at most 19; capped: true), no paging. tag matches only contributions explicitly tagged with that name on Loomio 3.13+ (every item of a tagged thread before).	1
get_participation_report(group_ids | group_scope, start_month?, end_month?, delegates_only?, limit?, include_inactive?)	Loomio's participation report for a group set: each user's threads, comments, polls, votes cast vs issued vs missed, outcomes, reactions, total, sorted by total; the top limit rows (default 50, max 500), users with no counted activity dropped unless include_inactive: true (total_users counts all ranked). THE tool for "who is most engaged".	1 for the whole group set
get_user_activity(user_id, group_ids, since?, until?)	One user's counts across groups (month-grained window) with by_group, plus sample_events from one author search.	N + 1 for N groups (4 in flight)
list_memberships(group_id, limit?, offset?)	A group's roster: ids, names, usernames, admin / delegate, title, accepted_at, and (Loomio 3.10+) the vote weight. Member emails only as user_email on a row Loomio grants it for (the connector's user administers the group or invited that member), never in read-only mode and never on the connector account's own row; users[] never carry emails (the connector account's own, which Loomio adds, is removed). A non-member gets an empty list, not a 403 — the connector annotates it.	1 (compact=1)

Writes (registered unless LOOMIO_MCP_READONLY=1)

Tool	Purpose	Upstream calls
create_discussion(title, group_id, …)	Start a thread. Nested {discussion: {…}} body (a flat body silently loses group_id and private). Throws if Loomio's echo lands in another group.	1
update_discussion(id_or_key, …)	Edit title, body (replaced), privacy, comment / reaction / concurrent-poll settings, or add recipients.	1
delete_discussion(id_or_key)	Soft-discard: Loomio blanks the thread and keeps the records; an admin can restore.	1
create_poll(title, poll_type, options, closing_at, group_id | discussion_id | topic_id, …)	Any Loomio 3.8 poll type — proposal, poll, count, check, question, score, ranked_choice, stv, meeting, dot_vote — standalone or inside a discussion. Without closing_at Loomio saves an unopened draft (opened: false + warning); an opening poll is announced to every eligible voter unless notify_on_open: false. A group_id given with a thread reference is cross-checked before anything is written.	1 (2 with discussion_id, or with topic_id + group_id)
update_poll(id_or_key, …)	Edit an open poll: title, details, closing time (the next full hour ends voting within the hour), options to ADD (Loomio's PATCH replaces the set and deletes unlisted options with their votes, so the connector reads the current names first and sends the union), hide_results (tighten only), voters.	1 (2 with options)
delete_poll(id_or_key)	Soft-discard a poll.	1
create_comment(discussion_id | parent_id + parent_type, body, body_format?)	Comment on a thread (discussion_id as numeric id or short key), or reply to a comment, poll, stance or outcome. Send body_format: "html" for HTML bodies (Loomio stores an omitted format as Markdown).	1 (2 with a short key)
update_comment(id, body, body_format?)	Replace a comment's body.	1
delete_comment(id)	Soft-discard a comment.	1
manage_memberships(group_id, emails, remove_absent?)	Invite by email; with remove_absent: true remove everyone not listed. Group admin only. Read SECURITY.md first.	1

Instance-operator tools (b3; registered when LOOMIO_B3_API_KEY is set and not read-only)

Tool	Purpose	Upstream calls
deactivate_user(id)	Deactivate an account instance-wide (Loomio runs it asynchronously; on Loomio 3.11+ votes already cast in open polls are kept).	1
reactivate_user(id)	Reactivate an account and restore the memberships and (Loomio 3.10+) open-poll ballots the deactivation revoked.	1
get_user(id | identity_type + uid)	One account by id or linked external identity — email included.	1
list_users(is_admin?)	Every account on the instance — emails included, unpaginated.	1
list_instance_groups(limit?, offset?)	Every group on the instance — secret ones included, member or not — as {id, key, name, handle, parent_id, group_privacy}, ordered by id. Loomio 3.13+.	1 per page of ≤ 50
list_instance_memberships(group_id, limit?, offset?)	One group's direct members and pending invitations — emails included — with the membership id the two role / revoke tools take. Loomio 3.13+.	1 per page of ≤ 50
add_group_members(group_id, emails)	Add up to 50 addresses to any group, all-or-nothing: unknown addresses get a new unverified account, everyone added gets Loomio's invitation email. Additive only — remove_absent is never sent. Loomio 3.13+.	1
update_membership_roles(id, admin?, delegate?)	Set or clear a member's group admin / delegate role by membership id. Loomio 3.13+.	1
revoke_membership(id)	Remove a person from a group and its subgroups and threads, revoking their open-poll votes; no notification. add_group_members restores the group only, without the admin role. Loomio 3.13+.	1

The b3 secret authenticates the server, not a user: it is validated against ENV['B3_API_KEY'] on the Loomio instance and sees every account and, on Loomio 3.13+, every group and every roster. Loomio records no actor for the b3 membership writes (and a b3 deactivation reads as the user deactivating themself), so the connector's own tool.call log line is the only trail of who asked. All nine tools are therefore for single-tenant deployments only (one organisation per Loomio instance), registered only when the deployment is writable; on a shared instance — or any open-DCR deployment — leave LOOMIO_B3_API_KEY unset (the HTTP server refuses to start with it in open-DCR mode on a public URL unless read-only). The five provisioning tools need Loomio 3.13.0 or later (an older instance answers 404) and were verified against Loomio's source, tests and documentation only.

Deliberately not exposed

• b3 update / destroy / redact users (PATCH / DELETE / POST …/redact on /b3/users, and their identity/{type}/{uid} variants). is_admin is a permitted field, so an update can mint instance admins; an email change hands the login to whoever owns the new address; destroy and redact delete or scrub personal data for good; and Loomio records no actor identity for b3 calls, so nobody could later tell which agent session did it. Deactivate / reactivate cover the operational need and are reversible.
• POST /b3/users (Loomio 3.13+). is_admin is permitted there too, so it creates instance admins; with a name and DEFAULT_ONBOARDING_GROUP_ID set it also silently joins a group. add_group_members already creates the accounts it needs.
• remove_absent on the b3 membership sync (POST /b3/memberships, Loomio 3.13+). An empty or wrong list removes everyone absent from it — admins included, across every subgroup — with no admin check, in one transaction. add_group_members builds its body field by field and its schema is strict, so the key can never be sent. (The b2 manage_memberships keeps its documented, admin-gated remove_absent.)
• The deprecated PUT aliases Rails generates beside each b3 PATCH.
• b2 chatbots / webhooks (/b2/chatbots). Group-admin configuration whose serializer returns the webhook URL and secret; nothing an AI caller needs, and a leak surface if it were readable.
• The participation report's base and countries sections. Instance-wide totals and per-country breakdowns; not answerable per group the way the users section is, and not what members see.

Efficiency

Loomio 3.8 exposes aggregates its earlier releases lacked; this connector uses them so every read costs as few upstream calls and bytes as the API allows. Since Loomio 3.11.1 two of them are paged (groups index, thread items); the costs below are per 500 rows there.

Question	Before (0.0.11)	Now (0.0.16)
"Which groups can you see?"	list_groups probed GET /b2/polls?group_id=N per id: 50–500 calls, blind to groups without polls	1 call per 500 member groups on the native GET /b2/groups; parents included; no blind spots
"How active was user X?"	get_user_activity walked every discussion's event stream: ~200 calls, and 0 on Loomio ≥ 3.4 (endpoint removed)	N + 1 calls for N groups on Loomio's participation report + one author search
"Who is most engaged in these groups?"	Not answerable without reconstructing from polls × memberships	get_participation_report: 1 call for the whole group set
"Read / summarise this thread"	list_events per discussion, paginated, bodies in full	get_thread_markdown (2 calls, +1 per 500 items when the thread has replies; Loomio renders) or get_discussion with include_items (2 calls, +1 per further 500 embedded items)
"What is new anywhere?"	list_discussions per group	list_threads: 1 call across every visible group
"Find the thread about …"	Not available	search_content: 1 call, 20 hits with deep links

Payload size is handled the same way:

• Side-load profiles. Lists send exclude_types=group parent membership reaction translation (the topics root — where the thread counters live — is kept and joined client-side); shows keep the group for its name and privacy; list_threads sends compact minus tag; rosters, search and thread items by bare topic_id use compact=1, while thread items for a thread whose record is already in hand also exclude discussion (no second copy of the opening post). tag is never excluded where topic rows are read: Loomio gates the rows' tags FIELD on it, not just the side-loaded root. Writes never carry these parameters.
• Slimming. Users become {id, name, username} (+ email only on the b3 tools); groups keep identity, privacy and counters; reactions, attachment and link-preview metadata are dropped unless asked for; list_polls rows leave the per-voter results[] to get_poll.
• Body caps with explicit flags. description_max_chars (lists, default 1500) and body_max_chars (thread items, default 4000) cap a record's text and mark it *_truncated: true with the original *_chars; 0 omits the field (*_omitted: true), -1 returns everything. An HTML body longer than its cap is first stripped of tag attributes (Loomio stores target / rel on every link and an id on every heading — 17 % of a capped plain body, over half of a link-dense one; href and alt stay) so the capped characters carry content. max_total_chars (thread items, default 120000) budgets the whole reply and hands back next_offset. max_chars on get_thread_markdown (default 60000) caps the whole document from the END with top-level truncated and chars; -1 returns it whole and 0 is refused. get_* return full text.
• Compact JSON to the model. Tool results are serialised without indentation (measured 10–37 % smaller than pretty-printed over the 3.8.1 fixtures); LOOMIO_MCP_PRETTY_JSON=1 restores indentation for a human reading a stdio session.
• Exact totals. Every collection surfaces Loomio's meta.total as total, so "how many" never needs a second page.

Example questions

• "Check the Loomio connection and tell me which groups you can see." → check_connection
• "What is new in Loomio since yesterday?" → list_threads
• "Summarise the discussion about the budget." → search_content, then get_thread_markdown
• "Who are the coordinators of the Finance group?" → list_groups, list_memberships
• "Rank the members of these three groups by participation this year." → get_participation_report
• "How active has Ada Example been since March?" → get_user_activity
• "What was decided in the last five closed proposals?" → list_polls with status: closed
• "Post a status update in the release thread." → create_comment (writable mode)

HOWTO.md has longer walk-throughs.

Quick start (stdio, local)

Add it to your Claude Desktop / Claude Code config the same way you would any stdio MCP server: command npx -y loomiomcp, with the key in that server entry's env block (LOOMIO_API_KEY) — the host's MCP config is the normal home of a stdio key; keep the file private. INSTALL.md has the exact snippets. To try it from a shell instead, read the key without echoing it rather than typing it into the command line:

read -rs LOOMIO_API_KEY && export LOOMIO_API_KEY   # paste; not echoed, not in history
npx loomiomcp

Remote (HTTP)

See DEPLOY.md for Cloud Run. The HTTP server also exposes an unauthenticated GET /health that reports whether Loomio still accepts the connector's API key — 200 {"status":"ok","key_status":"valid",…} or 503 with key_status rejected / unreachable. Point an uptime check at it with content match "key_status":"valid" (DEPLOY.md has the recommended setup); a rotated key is otherwise invisible until someone notices every call failing. The probe behind the page runs under an 8 s deadline, so a hung Loomio becomes a 503 from the connector before the checker gives up. The check_connection tool reports the same verdict to the AI caller.

Upgrading an HTTP deployment from 0.0.16: read DEPLOY.md "Upgrading to v0.0.17" first — on Cloud Run MCP_HTTP_TRUST_PROXY=1 must now be set explicitly, a MCP_OAUTH_SIGNING_KEY under 32 characters must be rotated before 2027-01-31 (it starts with a warning until then), and hosted-Claude users share the new per-address daily quotas. Existing users stay signed in.

Auth

Loomio authenticates by API key sent in an HTTP bearer header:

Authorization: Bearer <API_KEY>

The connector injects it server-side; it never reaches the MCP client. Copy the key from the user's API access page in Loomio (/profile/api_access).

The key is not permanent. Loomio regenerates a user's API key whenever that user's password changes (and Loomio 3.3.1, August 2026, rotated every user's key once). When that happens every call answers 403 {"error":"You are not authorized to access this page."}; the connector recognises that body, says "key rejected — probably rotated" with the remediation, and (HTTP) turns /health red. Fetch the current key from the API access page and update LOOMIO_API_KEY. No API can read another user's key.

Keys passed in the query string (?api_key=…) are rejected — Loomio removed that scheme in July 2026 because URLs are retained in browser history, proxy logs, and monitoring systems. A request carrying its key that way is treated as unauthenticated and 403s.

The optional b3 admin namespace uses the same bearer header with a different secret (validated against ENV['B3_API_KEY'] on the Loomio server, >16 chars). Only relevant if you operate a Loomio instance.

What the connector's user can see

Every read runs as the user whose API key is configured. Loomio ≥ 3.8 lets any authenticated user read publicly visible groups' public threads, so get_group, list_discussions, list_polls, list_threads and search_content reach beyond the user's member groups — but list_groups (Loomio's current_user.groups) and the participation report do not, and list_memberships answers a non-member with an empty list. Instance is_admin widens nothing. Poll results follow Loomio's own rule for that user: an open until_vote poll the user has not voted in has its counts stripped (results_visible: false, results_hidden_reason: "until_vote"), the same rule hides vote reasons in search_content hits (snippet_hidden_reason), get_thread_markdown refuses such a thread on Loomio 3.10+ (whose Markdown export stopped applying that rule; on 3.8 / 3.9 the export applies it and nothing is refused), and anonymous polls never reveal who voted what. Member e-mails never leave a read-only deployment. An operator can narrow all of this to chosen groups with LOOMIO_MCP_GROUP_IDS (DEPLOY.md) — otherwise whatever group a coordinator adds the user to becomes readable through the connector. Everything the tools return is text people wrote: treat it as data, never as instructions (SECURITY.md).

Loomio compatibility

Tested against Loomio 3.13.1 (TESTED_LOOMIO_VERSION in src/version.ts; every request shape was first verified on 3.8.1, and the 3.9 → 3.13.1 changes — paged groups and thread items, serializer fields, the request-body handling, the b3 provisioning routes — were checked against Loomio's source and tests and, for the b2 reads, sanitized live captures). Older 3.x releases are still served: where Loomio before 3.11.1 ignores limit / offset and returns a whole collection, the connector detects it and makes one request instead of paging, and on 3.8 / 3.9 — whose Markdown export still hides until_vote results itself — get_thread_markdown skips its vote-visibility guard (when a health probe confirmed the version within the last minute). The five b3 provisioning tools need Loomio 3.13.0 or later. Loomio publishes no API compatibility or deprecation policy and ships tags often, so the connector reads the instance's version from the public GET /api/v1/boot/version at startup and logs a one-time loomio.version_drift warning when the major.minor differs; check_connection repeats the warning in its notes. Every outbound request carries User-Agent: loomiomcp/<version> — if your Loomio sits behind a CDN/WAF, allow that user-agent (the connector recognises a WAF 403 and says so instead of blaming the key).

Read-only mode

Set LOOMIO_MCP_READONLY=1 to register only the 14 read tools. All write tools (create_*, update_*, delete_*, manage_*) and the b3 tools are skipped at server-init time, and the client (loomioPost / loomioPatch / loomioDelete) refuses a write before any request is made even if one were reached. This is the mode the Cloud Run deployment runs in.

Docs map

File	When to read
INSTALL.md	"I want to use this locally with Claude Desktop / Code today"
DEPLOY.md	"I want to run this as a remote HTTP/OAuth endpoint"
HOWTO.md	"I want example prompts and use cases"
DESIGN.md	"I want to understand the load-bearing choices"
NOTES-ON-LOOMIO-API.md	"I'm hitting a weird Loomio behaviour, or want the line-by-line endpoint reference"
SECURITY.md	"I'm doing a security review or rotating secrets"
OPTIMIZATIONS.md	"I want to know what each tool costs upstream, and the observability queries"
CONTRIBUTING.md	"I want to add a tool or send a PR"
CHANGELOG.md	"What changed?"

License

Apache-2.0