ManaWG MCP
Summary: ManaWG MCP lets an AI assistant act as your ManaWG account across shared flats, reading and managing flat data, finances, communication, and scheduling through MCP tools.
List flats and read flat overviews, dashboards, activity feeds, and bulk exports.
Read and manage expenses, splits, balances, settlements, and recorded cash payments.
List and manage fixed costs, including creating/editing recurring templates and booking due charges.
Read payment reminders and reminder history.
Manage noticeboard posts, reactions, comments, and chat messages/read state.
Read, create, and edit calendar events; record and list absences.
List members, read member balances, create invite links, and list active invites.
Read/update notification settings and manage calendar subscriptions.
Preview imports and list imports that can be undone.
Create new flats and operate within existing flats with membership-based access.
The hosted server supports non-destructive actions but omits destructive tools; it cannot delete a flat, change your account/sign-in, or move money.
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., "@ManaWG MCP Who owes whom in the flat, and how few payments would settle it all?"
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.
ManaWG is the free, open-source app for shared flats (WG, from the German Wohngemeinschaft). This server lets an assistant work with your flat the way you do in the app: it reads what is due, books what you just paid, puts milk on the list, and tells you who owes whom.
Connect an agent
Use the hosted server at https://mcp.manawg.com/mcp. Your client opens the browser, you
sign in to ManaWG and allow the assistant. There is no key to copy and nothing to install.
Client | How to add it |
Claude Code |
|
Claude (web, desktop) | Settings → Connectors → Add custom connector, URL |
ChatGPT | Settings → Apps & Connectors → Advanced settings → Developer mode, then Create with the URL and OAuth |
Cursor, VS Code, others | Add a streamable HTTP server with the URL |
No ManaWG account yet? Create one and a flat at app.manawg.com, or let
the assistant call wg_create once you are signed in.
Things to ask
"What is due in the flat this week?"
"I paid 42.80 € for groceries, split it between everyone except Jonas."
"Who owes whom, and what is the smallest number of payments to settle up?"
"Put oat milk and dish soap on the shopping list."
"I'm away from the 12th to the 19th, take me off the cleaning rota."
"Write a friendly reminder for the open balances, but don't send it."
Related MCP server: Hamara Hisaab
What the assistant can do
The assistant acts as your account, in all your flats, with the same rights you have in the app.
It can read everything you can see, create and edit expenses, fixed costs, shopping items, supplies, chores, posts, chat messages, events and absences, and settle debts the way the app does.
It cannot delete a flat, change your account or sign-in, or move money. ManaWG never moves money; settling up only records what you paid each other.
The hosted server leaves out all 22 destructive tools: deleting expenses, posts or items, changing flat or member settings, sending reminders, committing or undoing imports, emailing or revoking invites and rotating or revoking the calendar feed. Read tools carry
readOnlyHint, so clients can ask before every other call.You stay in control. Every assistant you connected is listed in the app under Settings → Access, and you can disconnect each one there.
The full list of 87 tools, 13 resources and 4 prompts is in docs/tools.md.
Area | Examples |
Overview |
|
Money |
|
Fixed costs |
|
Shopping and supplies |
|
Cleaning rota |
|
Noticeboard and chat |
|
Calendar and absences |
|
Flatmates and imports |
|
Prompts |
|
How it works
sequenceDiagram
autonumber
participant C as MCP client
participant M as mcp.manawg.com
participant S as Supabase Auth
participant A as app.manawg.com
C->>M: POST /mcp
M-->>C: 401 + protected resource metadata
C->>S: register client, start sign-in (PKCE)
S->>A: consent page
A-->>S: user signs in and allows
S-->>C: access token
C->>M: POST /mcp with bearer token
M->>M: verify token against the JWKS
M->>A: same call to the app API, with the token
A-->>M: data, checked against your membership
M-->>C: tool resultThe server is an OAuth 2.1 resource server as the MCP authorization spec describes it. Supabase Auth, which already runs the app's sign-in, is the authorization server. The MCP server stores nothing: it checks each token and forwards it, and the app applies the same membership checks as for your phone.
Each tool calls exactly one route of the app API. Money is in integer cents, every write carries
an idempotency key so a retried request is never booked twice, and writes that could race with a
flatmate fail instead of overwriting (chore_occurrence_changed, shopping_item_changed). Errors
come back as a code from a fixed allowlist, such as ManaWG request failed: splits_sum_mismatch.
Only validation errors add a truncated field-level detail. Upstream messages, URLs and credentials
are never forwarded.
Self-host
Run it on your own machine for a local agent over stdio, behind an API key over HTTP, or as your own OAuth server in front of your own ManaWG instance.
git clone https://github.com/Abuarchiv/manawg-mcp.git && cd manawg-mcp
pnpm install && pnpm build
mkdir -p ~/.config/manawg-mcp && cp .env.example ~/.config/manawg-mcp/env
chmod 600 ~/.config/manawg-mcp/env # then fill in your instance and account
claude mcp add manawg -- node --env-file="$HOME/.config/manawg-mcp/env" "$(pwd)/dist/index.js"Or with Docker: ghcr.io/abuarchiv/manawg-mcp (linux/amd64, linux/arm64).
The self-hosting guide covers both auth modes, every environment variable,
the HTTP transport, Docker and the Vercel deployment behind mcp.manawg.com.
Develop
You need Node.js 22 and pnpm 9. Tests, lint and typecheck need no credentials.
pnpm lint # Biome
pnpm typecheck # tsc --noEmit
pnpm test # Vitest: flows against a stateful stub app, API surface, OAuth
pnpm build # compile to dist/
pnpm smoke # stdio handshake against dist/
pnpm live-check # read-only probes against a real instance (credentials required)The tests run the real server, client and session code against a stub of the app that enforces its rules (Origin, cookies, idempotency keys, optimistic locking, strict bodies), and an API surface check keeps every tool mapped to a route the app actually has.
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md and the Code of Conduct first. Problems with the app itself belong in the app repository. Report security problems privately, see SECURITY.md. Changes are listed in CHANGELOG.md.
License
Apache License 2.0, like the ManaWG app. The licence does not grant rights to the name ManaWG or its logo.
Available Tools
65 toolsabsence_createRecord an absenceAInspect
Record that a flat member is away for a date range, for example a holiday. Use it for a person being away; use event_create for a calendar entry that concerns the whole flat. Members can record their own absence; recording one for another member needs a flat admin, otherwise 403 not_owner. The memberId must belong to an active member of this flat. An endDate before startDate fails with date_range_invalid. An absence that overlaps another absence of the same member (by Berlin calendar day) fails with 409 absence_overlaps_existing. Returns the created absence with its id.
Inputs: endDate (required), memberId (required), startDate (required), reason, +1 more.
absences_listRead absencesARead-onlyIdempotentInspect
List the absences of flat members that are running or still ahead (an absence stays listed until its end date has passed, counted in Berlin time), ordered by start. Use it to see who is away; use events_list for flat calendar events, absence_create to record a new absence and absence_delete to remove one. Each entry has id, memberId, memberName, startDate, endDate (ISO 8601) and reason (text or null); the id is what absence_delete needs.
Inputs: wgCode.
activity_getRead the activity feedARead-onlyIdempotentInspect
Returns the newest timeline entries of the flat, 80 by default and up to 320 with limit, plus active reminders. Timeline entries cover expenses, shopping, announcements, chore completions, recurring costs, absences and audit events. Reminders (kind, title, detail, href; top 6, independent of limit) cover open shopping items, overdue chores and open announcements. Use it to see what happened recently and who did it. There are no filters and no cursor; for older history use export_get, for current totals and balances use dashboard_get. Read-only; any member of the connected flat may call it.
Inputs: limit, wgCode.
balances_getRead open balancesARead-onlyIdempotentInspect
Lists what other members currently owe the caller (creditor view), one entry per debtor and currency with debtor_id, debtor_name, amount_cents (cents), currency and oldest_age_days. Read only. Use it to find who to remind with reminder_send; the result is empty when nobody owes the caller. It does not show what the caller owes or debts between other members (use dashboard_get), and gives no settlement detail (use settlement_preview).
Inputs: wgCode.
calendar_subscription_createCreate the calendar subscriptionAIdempotentInspect
Create the caller's own calendar feed for the flat, so a calendar app can subscribe to the flat's events. Use it when calendar_subscription_get returns subscription null; to read an existing feed use calendar_subscription_get, to replace a leaked URL use calendar_subscription_rotate. Safe to repeat: if a feed is already active it is returned unchanged; after calendar_subscription_revoke it creates a fresh feed with a new URL. Any member may call it; it notifies nobody. Returns subscription { feedUrl, createdAt, updatedAt }. feedUrl contains a secret token that grants read access to the flat's events, so show it only to the user and never post it in chat, notes or logs.
Inputs: wgCode.
calendar_subscription_getRead the calendar subscriptionARead-onlyIdempotentInspect
Read the caller's own calendar feed subscription for the flat. Returns subscription { feedUrl, createdAt, updatedAt }, or subscription null when no feed is active; then call calendar_subscription_create. Use it to give the user a URL to add to a calendar app; to list the events themselves use events_list. Read-only; any member may call it, and each member has their own feed. feedUrl contains a secret token that grants read access to the flat's events, so show it only to the user and never post it in chat, notes or logs.
Inputs: wgCode.
cash_payment_recordRecord a cash paymentAInspect
Records a cash payment that already happened over the whole current net debt from fromMemberId to toMemberId; ManaWG moves no money. Use it once the debt was handed over; to mark only selected shares use settlement_commit or expense_split_settle, to take a wrong entry back use cash_payment_void. The caller must be one of the two members (otherwise not_party_to_debt), both active in the flat (member_not_in_wg). expectedNetCents guards against a changed debt: 409 settlement_changed means run settlement_preview again. Notifies the other member and writes an audit entry.
Inputs: toMemberId (required), fromMemberId (required), expectedNetCents (required), wgCode, +1 more.
chat_editEdit a chat messageAInspect
Replaces the text of a message you sent yourself, within 15 minutes of sending; the message is then marked as edited and its mentions are recalculated from the new text. Other members' messages, deleted messages and older messages give 403 edit_not_allowed, an unknown id gives message_not_found, and a message deleted in the meantime gives 409 message_deleted. To post a new message use chat_send, to remove one use chat_delete. Returns the updated message.
Inputs: id (required), body (required), wgCode.
chat_mark_readMark the chat as readAIdempotentInspect
Records that the signed-in member has read the chat up to a message, which lowers the chat_unread count and updates the read position other members see in chat_messages. The marker only moves forward: an older message id is ignored, and the response says whether the marker moved. An id that is not in this flat gives message_not_found. Use this after reading with chat_messages; it does not read or send anything.
Inputs: wgCode, lastReadMessageId.
chat_messagesRead the chatARead-onlyIdempotentInspect
Reads one page of the flat chat, newest messages by default, in chronological order. Use it to catch up or to find a message id for chat_edit, chat_react, chat_delete or chat_mark_read; it does not change the read marker (use chat_mark_read) and does not count unread messages (use chat_unread). To page back, send beforeId of the oldest message you have; a malformed id gives before_id_invalid. The result holds messages, their reactions and mentions, and each member's read position; deleted messages show no text.
Inputs: limit, wgCode, beforeId.
chat_reactAdd a chat reactionAIdempotentInspect
Adds your emoji reaction to any message in the flat chat; you can add several different emojis to one message. Each member holds a given emoji at most once per message, so an emoji you already set stays as it is. Does not change or post message text. Returns ok. Only a single emoji (one pictograph, flag or keycap, with skin-tone or joiner sequences counting as one) is accepted, otherwise emoji_invalid; an unknown message gives message_not_found and a deleted one 409 message_deleted. To take a reaction back use chat_unreact; to write a message use chat_send.
Inputs: id (required), emoji (required), wgCode.
chat_sendSend a chat messageAInspect
Posts a new text message to the flat chat as the signed-in member; use chat_edit to change a message you already sent. Notifies the other members, and anyone mentioned gets a separate mention notification, so confirm the wording with the user first. Text only, no images; a blank body gives empty_message. A reply target that is missing or deleted gives reply_to_not_found. Each call creates a new message, so do not retry blindly. Returns the created message, the mentioned member ids and a warning that is null unless the push delivery could not be confirmed.
Inputs: body (required), wgCode, mentionMemberIds, replyToMessageId.
chat_unreactRemove a chat reactionAIdempotentInspect
Removes your own emoji reaction from a message; other members' reactions stay. Removing a reaction you never set changes nothing, so repeating the call is safe. An unknown message gives message_not_found and a deleted one 409 message_deleted. To add a reaction use chat_react.
Inputs: id (required), emoji (required), wgCode.
chat_unreadCount unread messagesARead-onlyIdempotentInspect
Counts the chat messages the signed-in member has not read yet, without returning them or changing anything. Returns count (capped at 99), exactCount and overflow (true from 100 unread). Use it for a cheap check before chat_messages; clear the count with chat_mark_read.
Inputs: wgCode.
chore_completeComplete a choreAInspect
Mark the current round of a chore as done by the calling member. The app schedules the next due date from the cadence, moves the chore to the next available member in the rotation (skipping absent members), and closes an open swap request for it. Call chores_list first and pass the chore's current nextDueAt and assignedMemberId as the expected values so a stale or double completion is rejected. Returns chore_occurrence_changed if the chore moved on since you read it: read again and decide again, do not retry blindly. Returns chore_already_completed if this round was just completed. Not for editing a chore: use chore_update. The response holds the updated chore and completion { id, previous { nextDueAt, assignedMemberId, anchorAt } }; keep them to take a mistaken completion back with chore_complete_undo.
Inputs: id (required), expectedNextDueAt (required), expectedAssignedMemberId (required), wgCode.
chore_complete_undoUndo a chore completionAInspect
Take back the caller's own latest completion of a chore: the app restores the due date, assignee and anchor from before the completion, reopens the swap request the completion closed and removes the completion from the history. Use it right after chore_complete when it was a mistake; to change a chore for any other reason use chore_update. Only the member who completed can undo (not_owner for others), only the latest completion, and only within about two minutes after the chore last changed (undo_expired afterwards, not_latest_completion if a later completion exists, completion_not_found if it was already undone). Returns chore_changed if the chore moved on since the completion: read it again. Not idempotent: a second call fails. Pass back the completion and chore values exactly as the chore_complete response returned them. Returns the restored chore.
Inputs: id (required), previous (required), completionId (required), expectedNextDueAt (required), +2 more.
chore_createCreate a choreAInspect
Create a new recurring chore in the flat. Use for a task that repeats on a fixed rhythm; to mark an existing chore as done use chore_complete, and to change an existing chore use chore_update. If nextDueAt is omitted the first due date is one interval from now. A chore assigned to another member that is due within 24 hours sends that member a push notification; self-assignment does not. An assignee who is not an active member fails with member_not_in_wg. Returns the created chore.
Inputs: title (required), wgCode, nextDueAt, intervalDays, +2 more.
chore_getRead one choreARead-onlyIdempotentInspect
Fetch a single chore by id with its schedule (title, intervalDays, recurrenceType, nextDueAt, assignedMemberId). Use when you already know the id; use chores_list to find ids, see all chores, or read last completion data, which this tool does not include. Returns chore_not_found if the id is not a chore of this flat.
Inputs: id (required), wgCode.
chores_listRead the cleaning rotaARead-onlyIdempotentInspect
List every recurring chore of the flat, soonest nextDueAt first. Each chore carries assignedMemberId, intervalDays, recurrenceType, nextDueAt, lastCompletedAt and lastCompletedByName; the response also has monthCompletions (completions this month per member id). Use this to see who is due and as the required read before chore_complete, which needs nextDueAt and assignedMemberId from here. For a single chore use chore_get.
Inputs: wgCode.
chore_swap_requestAsk the flat to take over a choreAInspect
Posts a swap request for one chore to the flat noticeboard as the signed-in member and sends a push notification to the other members; it differs from note_create in that the post is tied to the chore. Use it when you cannot do a chore and want someone else to take it; for a general message use note_create. Only one open swap request exists per chore: if one is already open, nothing new is posted and the existing post is returned with duplicate true. The request closes automatically when the chore is reassigned with chore_update or completed with chore_complete, or by hand with note_update. An unknown choreId is not rejected: the post is then stored as an ordinary manual post. The answer holds the announcement and a warning when the push delivery could not be confirmed.
Inputs: choreId (required), content (required), kind, wgCode.
chore_updateEdit a choreAInspect
Change the title, assignee, next due date or rhythm of an existing chore; send only the fields to change. Use this to rename, reassign or reschedule. To record that the chore was done use chore_complete, which also rotates the assignee. Any member may edit. Handing a chore due within 24 hours to another member sends that member a push notification. Pass expectedUpdatedAt (the updatedAt from chore_get or chores_list) to reject the edit when someone else saved the chore since. Returns chore_not_found for an unknown id, member_not_in_wg for an assignee who is not an active member and chore_changed if the chore was changed by someone else in the meantime: read the chore again and retry. Returns the updated chore.
Inputs: id (required), title, wgCode, nextDueAt, +4 more.
dashboard_getRead the dashboardARead-onlyIdempotentInspect
Returns the compact overall picture of the flat in one call: balances, spendByDay, spending totals in cents (per currency in totalSpendByCurrency, weekSpendByCurrency, monthSpendByCurrency), openShoppingCount, openShoppingTop, dueChores, activity, latestAnnouncement, myOpenAnnouncements, dueRecurringExpenses, absentMembers and wgHealth setup state. Use it for a quick status check; for full lists use the dedicated tools such as expenses_list, shopping_list or chores_list, and for the event history use activity_get. Read-only; limited to 60 reads per minute per member (error rate_limited).
Inputs: wgCode.
event_createCreate a calendar eventAInspect
Add a new event, one-off or repeating, to the flat calendar. Use it for something new; use event_update to change an existing event, and absence_create instead when a member is away. Not idempotent: calling it twice creates two events. The other flat members are notified about the new event, not the caller. An endsAt before startsAt fails with ends_before_start. Returns the created event with its id and a warning that is null unless the push delivery could not be confirmed.
Inputs: title (required), startsAt (required), allDay, endsAt, +4 more.
event_getRead a calendar eventARead-onlyIdempotentInspect
Fetch one calendar event with all its fields, including updatedAt, the version token event_update takes as expectedUpdatedAt. Use it when you have an event id and want its current state, for example before editing; use events_list to browse or find events. An id that is not in this flat fails with 404 event_not_found.
Inputs: id (required), wgCode.
events_listRead calendar eventsARead-onlyIdempotentInspect
List the flat calendar events, optionally inside a time window, ordered by start. Use it to see what is planned or to find an event id; use event_get when you already have the id, and calendar_subscription_get for the feed URL that adds the calendar to a calendar app. A recurring event comes back once with its recurrence rule, not expanded into single dates. Send from and to together to limit the window; without them all events are returned. More than 1000 matches fail with 503 events_window_too_large, so narrow the window. Each event has id, title, description, startsAt, endsAt, allDay, location, recurrence, createdByMemberId and updatedAt.
Inputs: to, from, wgCode.
event_updateEdit a calendar eventAInspect
Change fields of an existing event; fields you leave out stay unchanged, and description, location, recurrence and endsAt can be cleared by sending null. Use event_create for a new event and event_delete to remove one. Only the event creator or a flat admin may edit it, otherwise 403 not_owner. For a recurring event the change applies to the whole series; use event_occurrence_change to cancel or move a single date. When the start or allDay changes and the event is still upcoming (or repeating), the other members are notified that it moved. Pass expectedUpdatedAt to guard against concurrent edits: if someone changed the event since, you get 409 event_changed, so read it again with event_get and decide. An endsAt before startsAt fails with ends_before_start. Returns the updated event.
Inputs: id (required), title, allDay, endsAt, +6 more.
expense_createCreate an expenseAInspect
Creates one expense in the flat, paid by the caller or by paidByMemberId and divided into debtor splits whose sum must equal amountCents (otherwise splits_sum_mismatch). Use it for a new purchase or for booking a due fixed cost; to change an existing expense use expense_update, to repay a debt use cash_payment_record or settlement_commit. If someone else paid, the caller must carry a positive share (otherwise paid_by_must_include_caller). To book a due fixed cost send recurringExpenseId and expectedRecurringNextDueAt together (nextDueAt from recurring_get): the expense is created and the template advanced in one step. Side effects: posts a chat notice and notifies the other members by push, not the caller. The answer holds the created expense and a warning that is null when notifications went out normally.
Inputs: splits (required), amountCents (required), description (required), wgCode, +7 more.
expenses_listRead expenses and paymentsARead-onlyIdempotentInspect
Lists the flat's expenses, newest first by occurredAt, each with its splits (debtorMemberId, amountCents, settledAt) and the recorded cash payments, one page at a time. Use it to find an expense, split or payment id, to check updatedAt before expense_update, or to review history. For what others owe the caller use balances_get, for the amount to settle between two members use settlement_preview. Read only. The answer carries expenses, payments, total (all expenses) and hasMore; payments are returned in full on every page.
Inputs: limit, offset, wgCode.
expense_split_settleMark a split as settledAInspect
Marks one debtor share of an expense as settled (the person paid it back in cash), or reopens it with settled false; the expense itself stays unchanged. Use it for a single share; to settle several shares between two members use settlement_preview then settlement_commit, to settle the whole net debt use cash_payment_record. Only the debtor or the payer of that expense may call it (otherwise not_split_party). Settling is refused with 409 split_already_offset when the share is larger than what the debtor still owes net, and split_not_found when the split id does not belong to the expense. Settling notifies the other party; reopening does not. The answer holds the split.
Inputs: id (required), splitId (required), wgCode, settled.
expense_updateEdit an expenseAInspect
Edits an existing expense: description, category, total amount, splits or receipt image. Only the payer may edit (otherwise not_payer). To remove an expense, use expense_delete. Send only the fields to change. A new amountCents needs the complete replacement splits in the same call (splits_required_with_amount), and the currency cannot be changed. Splits that stay the same keep their settled state. Pass expectedUpdatedAt (updatedAt from expenses_list) to refuse a stale edit: 409 expense_changed means read again and decide. Side effects: members whose share changed get a push, and the chat notice is refreshed when description or amount changes. The answer holds the updated expense.
Inputs: id (required), splits, wgCode, category, +4 more.
export_getExport flat dataARead-onlyIdempotentInspect
Exports the stored data of the flat for backup or analysis. With format json (default) it returns the requested sections, or all of them when sections is omitted; with format csv it returns exactly one section (expenses when omitted) as { contentType, content }. Members are never paged; limit and offset page every other section. Use the specific list tools for everyday reads and this one only for bulk dumps. Read-only; limited to 20 exports per hour per member (error rate_limited).
Inputs: limit, format, offset, wgCode, +2 more.
import_previewPreview an importARead-onlyInspect
Dry-run parse of expense data exported from another app (Splitwise, Splid, Tricount or Settle Up CSV) or pasted receipt text, without writing anything. Call this first, then import_commit with the same source and payload. Returns parsed (expense rows), payloadHash, memberMapping (file name to member id or null), conflicts (names still unmapped), members (active members of the flat), rejected (rows that could not be parsed) and fuzzyNames (names matched only approximately; check them). Names are matched to members automatically, and any entry you pass in memberMapping overrides that match. Rate limit: 10 previews per hour per member.
Inputs: source (required), payload (required), wgCode, memberMapping.
imports_listList imports that can be undoneARead-onlyIdempotentInspect
List the latest imports (up to 10, newest first) that import_undo can still take back, each with id, source, startedAt, inserted (expenses created) and importedByMemberId. Use it to find the importId of an import_commit from an earlier session; imports with settled shares are left out. Admins see all imports of the flat, other members only their own. Read-only. For the preview of new data use import_preview.
Inputs: wgCode.
inventory_addAdd a supply itemAInspect
Creates a new supply item in the flat. Use it only for a product that is not tracked yet; to change stock of an existing item use inventory_consume or inventory_update. Item names are unique per flat, ignoring case and surrounding spaces; a taken name fails with 409 inventory_item_duplicate. If the starting quantity is already <= threshold (which the defaults give), the item is put on the shopping list automatically. Returns the created item.
Inputs: name (required), unit, wgCode, category, +2 more.
inventory_consumeUse up stockAInspect
Records that stock of one item was used up by lowering its quantity; use it for everyday use (someone took a roll) instead of inventory_update. Stock never goes below 0. When this use takes the item from above threshold to at or below it, the item is added to the shopping list and the other flat members get a low-stock notification (not the caller). Returns the item, clamped (true when the change was limited at 0), autoPushedShoppingItemId (shopping item created, or null) and a notification warning. Concurrent uses are applied one after another; a rare race gives 409 version_conflict, then retry. Unknown ids give 404 item_not_found. To restock or correct stock use inventory_update.
Inputs: id (required), delta (required), wgCode.
inventory_listRead suppliesARead-onlyIdempotentInspect
Lists all household supply items (toilet paper, detergent and similar) of the flat with quantity, unit, threshold, category and decrementCount30d (times the stock was reduced in the last 30 days). An item is low on stock when quantity <= threshold. Read-only. Call it first to get the item ids that inventory_update, inventory_consume and inventory_remove need, and to check for an existing item before inventory_add. Not for the shopping list; use shopping_list for that.
Inputs: wgCode.
inventory_updateEdit a supply itemAInspect
Edits one supply item: rename it, change unit, category or threshold, or change its stock. For stock use quantityDelta to add or subtract (restock or relative change, no version check) or quantity to set an absolute value after a stocktake; the absolute form requires expectedQuantity and expectedUpdatedAt from a fresh inventory_list and fails with 409 version_conflict if the item changed since, so read again and retry. To record that something was used up, prefer inventory_consume. Send only the fields to change; an empty update fails with empty_update. A rename to a name already in the flat fails with 409 inventory_item_duplicate. A change that moves the stock from above to at or below threshold puts the item on the shopping list. Returns the updated item; unknown ids give 404 item_not_found.
Inputs: id (required), name, unit, wgCode, +6 more.
invite_createCreate an invite linkAInspect
Create a link that lets one or more people join the flat; this is the only way to add flatmates, because the share code alone does not allow joining. The link works for 14 days and for up to 10 joins, and a flat holds at most 20 active links (invite_limit_reached; free one with invite_revoke). Use it when the user wants to hand the link over themselves; to send it by email use invite_email instead, to see existing links use invites_list. Any member may call it. Not idempotent: every call creates a new link. Returns id, url and expiresAt. url is a secret that lets anyone who has it join the flat, so show it only to the user and never post it in chat, notes or logs. It cannot be read again later, because invites_list never returns it.
Inputs: wgCode.
invites_listList active invite linksARead-onlyIdempotentInspect
List the active invite links of the flat, newest first, each with id, createdAt, expiresAt, maxUses, useCount and createdByName. Links that expired, were revoked or reached their use limit are not listed. Use it to find the id for invite_revoke or to see whether a link was used; it never returns the link URL itself (only invite_create does), so a lost link has to be revoked and recreated. Read-only; any member may call it.
Inputs: wgCode.
member_getRead a member and their open balancesARead-onlyIdempotentInspect
Read one member (id, name, active) plus openBalances: every unsettled debt between them and each other member, with member_id, name, amount_cents, currency and direction owes (this member still owes the other) or owed (the other owes them). Use it before member_update to see what money would be left open on a move-out. For all members at once use members_list, for what others owe you use balances_get, for debts between all members dashboard_get. Read-only; unknown ids give member_not_found.
Inputs: id (required), wgCode.
members_listList membersARead-onlyIdempotentInspect
List every member of the flat, including moved-out ones, with id, name, color, active and viewerIsAdmin, plus pagination total/limit/offset. Use it to look up member ids for other tools (payer, assignee, split debtor) or to find who is active; filter on active yourself. For one member and their open balances call member_get, for what others owe you call balances_get. Read-only.
Inputs: limit, offset, wgCode.
note_commentAdd a comment to a postAInspect
Adds a comment to an existing noticeboard post as the signed-in member and pushes a notification to the post author and the takers (not to you). Use it to reply on a post; to start a new topic use note_create, and for the live conversation use chat_send. The answer holds the created comment (with its id, authorName and authorColor) and a warning when the push delivery could not be confirmed. Returns 404 announcement_not_found for an unknown post.
Inputs: id (required), content (required), wgCode.
note_commentsRead the comments on a postARead-onlyIdempotentInspect
Reads the comments of one noticeboard post, oldest first (max 500), each with id, memberId, content, createdAt, authorName and authorColor. Use it when you only need one post; notes_list already embeds comments for all posts. To add a comment instead of reading them, use note_comment. Returns 404 announcement_not_found for an unknown post id.
Inputs: id (required), wgCode.
note_comment_updateEdit your own commentAInspect
Replaces the text of one of your own comments on a noticeboard post; nobody is notified. Only the comment author may edit it, not even an admin (403 not_owner); an unknown comment returns 404 comment_not_found. To remove a comment use note_comment_delete; to add a new one use note_comment.
Inputs: id (required), content (required), commentId (required), wgCode.
note_createWrite a postAInspect
Posts a new message to the flat noticeboard as the signed-in member and sends a push notification to the other members. Use it for announcements, questions or requests to the whole flat; to ask for a chore to be taken over use chore_swap_request, to reply on an existing post use note_comment, and for the live conversation use chat_send. The answer holds the created announcement and a warning when the push delivery could not be confirmed. An imageUrl that is not an app-issued upload of this flat fails with image_invalid; an upload that was deleted fails with image_removed.
Inputs: content (required), kind, wgCode, imageUrl.
note_reactSet a reactionAIdempotentInspect
Sets or removes your own seen, ok or take reaction on one noticeboard post. seen means you read it, ok means you agree, take means you will handle it: it lets you resolve the post via note_update and makes you a taker, who is notified about new comments and when the post is resolved. Reaction kinds are independent, so you can hold several on one post. Use it to react, not to write text; use note_comment to reply. The call states the desired end state, so repeating it is safe and changes nothing. Reactions notify nobody. Any flat member may call it. Returns the reaction and active as stored. Setting take on an already resolved post fails with 409 announcement_resolved; reopen it first with note_update. Returns 404 announcement_not_found for an unknown post id.
Inputs: id (required), active (required), reaction (required), wgCode.
notes_listRead the noticeboardARead-onlyIdempotentInspect
Lists the flat noticeboard: member-written posts, pinned first, then newest first (max 300). Each post carries kind, status, updatedAt, reactionCounts, myReactions, takers (members who reacted with take) and its comments. Finished posts (resolved, or info/decision) drop off the board 30 days after their last activity unless pinned; open questions, problems and requests stay. A post with source chore_swap is a swap request for a chore; chore_update with a new assignee or chore_complete closes it. Use this to find post ids and updatedAt for note_update; use note_comments to read the comments of one post by id.
Inputs: wgCode.
note_updateEdit a postAInspect
Edits an existing noticeboard post: resolve or reopen it, pin or unpin it, change its kind, or rewrite its text. Send only the fields you want to change. content, pinned and kind may only be changed by the post author or an admin (otherwise 403 not_owner); content only on manually written posts (otherwise 403 content_locked). status may only be changed by the author, an admin, or a member who has set a take reaction on the post (otherwise 403 status_change_not_allowed). Resolving a post pushes a notification to the author and the takers. Pass expectedUpdatedAt to guard against concurrent edits: if the post changed meanwhile the call fails with 409 announcement_changed, so read notes_list again before retrying. To remove a post use note_delete; to take it on use note_react.
Inputs: id (required), kind, pinned, status, +3 more.
notifications_getRead notification settingsARead-onlyIdempotentInspect
Read your own notification settings in this flat: the notify* flags per area (announcements, chores, expenses, shopping, inventory, reminders, chat, events, statement email), quietStartHour/quietEndHour (0-23 or null), pushOptIn and pushConfigured (whether the server can send push at all). Call it before notifications_update to see current values. Settings belong to the calling member only; other members cannot be read or changed. Read-only.
Inputs: wgCode.
notifications_updateChange notification settingsAIdempotentInspect
Change your own notification settings in this flat: any subset of the notify* flags, pushOptIn and quiet hours; omitted fields stay as they are. Use it to mute areas or set quiet hours; to read current values call notifications_get first. Quiet hours use Europe/Berlin time and are skipped for urgent events. pushOptIn false deletes all your push subscriptions, and true does not subscribe a device (that happens in the app). Invalid quiet hours give quiet_hours_invalid. Sending an empty object changes nothing and answers ok. Affects only the calling member and notifies nobody. Cannot change other members or flat settings (see wg_update).
Inputs: wgCode, pushOptIn, notifyChat, notifyChores, +9 more.
recurring_advanceAdvance a fixed cost nowAInspect
Skip ahead one cycle: moves ONLY nextDueAt on by intervalMonths, without creating an expense. It only works once an expense was booked for the current due date, otherwise 409 recurring_expense_not_booked, and a paused template answers 400 recurring_paused. Any member may call it. To book the due payment use expense_create with recurringExpenseId and expectedRecurringNextDueAt instead: it creates the expense and advances the template in one step. To change the schedule itself use recurring_update. expectedNextDueAt is required and prevents double advancing: if the cycle was already advanced, 409 recurring_expense_already_advanced and nothing changes. Returns the updated template as recurringExpense.
Inputs: id (required), expectedNextDueAt (required), wgCode.
recurring_createCreate a fixed costAInspect
Create a new fixed-cost template (for example monthly rent) that the app books automatically as an expense every intervalMonths, starting at nextDueAt. Use it for charges that repeat; for a one-off payment use expense_create. It does not book a charge itself. Any member may create one. If paidByMemberId is not you, you must carry a positive share in splits, otherwise 403 paid_by_must_include_caller; members who left fail with 400 member_not_in_wg. Returns the new template as recurringExpense. The call carries an idempotency key, so a retried request is not created twice.
Inputs: splits (required), nextDueAt (required), amountCents (required), description (required), +5 more.
recurring_getRead one fixed costARead-onlyIdempotentInspect
Read one fixed-cost template with its splits, by id. Use it to get the current nextDueAt before recurring_update or recurring_advance; use recurring_list when you do not know the id yet. Read-only. Answers 404 recurring_expense_not_found for an unknown id or an id of another flat.
Inputs: id (required), wgCode.
recurring_listRead fixed costsARead-onlyIdempotentInspect
List all fixed-cost templates (recurring expenses such as rent or internet) of the flat, ordered by nextDueAt, at most 500. Use it to find a template id or to see what is due next; use recurring_get for a single template and expenses_list for charges that were already booked. Read-only. Each entry has description, category, amountCents, paidByMemberId, intervalMonths, nextDueAt, pausedAt (null when active) and splits; currency is always EUR.
Inputs: wgCode.
recurring_updateEdit or pause a fixed costAInspect
Change a fixed-cost template or pause and resume it (paused). Send only the fields to change; at least one is required (400 invalid_body otherwise). Use it for edits and pausing; to skip one cycle use recurring_advance, to remove the template for good use recurring_delete. Only the creator of the template or a flat admin may call it, others get 403 not_owner. Resuming does not book the missed cycles: the due date jumps to the next cycle day from today. Changing amountCents, paidByMemberId or splits is checked like recurring_create (403 paid_by_must_include_caller, 400 splits_sum_mismatch). Pass expectedNextDueAt to guard against concurrent edits or bookings: if the template moved meanwhile, the call fails with 409 recurring_expense_changed and nothing is written; read it again with recurring_get and decide. Returns the updated template as recurringExpense.
Inputs: id (required), paused, splits, wgCode, +8 more.
reminders_listRead the reminder historyARead-onlyIdempotentInspect
Lists the payment reminders sent in the flat in the last 30 days, newest first, at most 50, each with channel, message, amountCents, currency, oldestDebtAgeDays and sentAt. Read only. Use it to check whether a reminder went out recently before calling reminder_send (which has a 48 h cooldown per debtor); for who owes the caller money use balances_get.
Inputs: wgCode.
settlement_commitCommit a settlementAInspect
Marks the open splits listed by a settlement_preview as settled in one step, for the debt from fromMemberId to toMemberId. Run settlement_preview first and pass its result unchanged as expected; if the debts changed in between, the call fails with 409 settlement_changed, then preview again. Use it to settle several shares at once; for one share use expense_split_settle, to record a cash payment over the whole net debt use cash_payment_record. The caller must be one of the two members (otherwise not_party_to_debt). Moves no money. Notifies the other member and writes an audit entry.
Inputs: currency (required), expected (required), toMemberId (required), fromMemberId (required), +1 more.
settlement_previewPreview a settlementARead-onlyIdempotentInspect
Computes, without changing anything, what settling the debt from fromMemberId to toMemberId would cover: netCents (net debt), settleableCents, remainingCents and the affected splits. Call it before settlement_commit (pass the result as expected) or cash_payment_record (use netCents as expectedNetCents). For a quick overview of what others owe the caller use balances_get instead. The caller must be one of the two members (otherwise not_party_to_debt); both must be active in the flat (member_not_in_wg).
Inputs: toMemberId (required), fromMemberId (required), wgCode, currency.
shopping_addAdd a shopping itemAInspect
Add one item to the flat's shared shopping list, optionally with a quantity. Use it when something needs to be bought; to tick off an existing item use shopping_set_bought, and to track household stock use inventory_add. Every other member gets a notification (a system notice and a push; the caller is excluded). Fails with 409 shopping_item_duplicate when an open item with the same name already exists, so read shopping_list first instead of retrying. Rate limited per member (too_many_requests with retry_after_s). Returns the created item.
Inputs: name (required), bought, wgCode, quantity.
shopping_listRead the shopping listARead-onlyIdempotentInspect
Read the flat's shopping list: every open item (oldest first), followed by the most recently bought items (newest first, capped at about 1000). Each item has id, name, quantity, addedBy/addedByName, boughtBy, boughtAt (null while open) and updatedAt. Call it first to get the id (for shopping_set_bought and shopping_remove) and the updatedAt and boughtAt that shopping_set_bought requires, or to check for an open duplicate before shopping_add. For supplies stock instead of things to buy, use inventory_list.
Inputs: wgCode.
shopping_set_boughtMark an item as boughtAInspect
Mark one open item as bought, or put a bought item back on the open list (bought=false). Any member may do it. It only changes the bought state: to rename the item or change its quantity use shopping_update, and to delete it use shopping_remove. Uses optimistic locking: call shopping_list first and pass the item's updatedAt and boughtAt unchanged. If someone changed the item in between, the call fails with 409 shopping_item_changed and nothing is written: read the list again and decide again. If the item is already in the requested state the call succeeds without changes. Marking as bought records the caller as boughtBy and sets boughtAt to now; reopening clears both. Reopening can fail with 409 shopping_item_duplicate when another open item has the same name. Returns the updated item; item_not_found for an unknown id.
Inputs: id (required), bought (required), expectedBoughtAt (required), expectedUpdatedAt (required), +1 more.
shopping_updateEdit a shopping itemAInspect
Rename a shopping item or change or clear its quantity, for example to fix a typo or a wrong amount, keeping its id, adder and bought state. Any member may do it. Send only the fields to change, at least one of name and quantity. To tick an item off or reopen it use shopping_set_bought; to delete it use shopping_remove. Uses optimistic locking: call shopping_list first and pass the item's updatedAt and boughtAt unchanged. If someone changed the item in between, the call fails with 409 shopping_item_changed and nothing is written: read the list again and decide again. Renaming to the name of another open item fails with 409 shopping_item_duplicate. Nobody is notified. Returns the updated item; item_not_found for an unknown id.
Inputs: id (required), expectedBoughtAt (required), expectedUpdatedAt (required), name, +2 more.
wg_createCreate a new flatAInspect
Create a new, separate flat with the caller as its first member and admin. Use it only when the user wants a new flat; to change an existing flat use wg_update, to see the flats the account already belongs to use wg_list. Works on the account level, so wgCode is not needed. Returns wg { id, shareCode, name } and creator { id, name }; pass shareCode as wgCode to other tools to work in the new flat. The share code only addresses the flat in tools; people cannot join with it, so to add flatmates create an invite link with invite_create or send one with invite_email. Fails with account_deletion_pending if the account is being deleted and with wg_create_rate_limited after 10 creations per hour from one IP address.
Inputs: name (required), creatorName (required).
wg_listList your flatsARead-onlyIdempotentInspect
Lists every flat the signed-in account is an active member of, each with id, name, share code (code) and your memberId in it. Use it first when the account belongs to several flats, then pass the chosen code as wgCode to every flat-scoped tool; wg_list and wg_create work on the account and take no wgCode. To see the members and details of one flat, call wg_overview instead. Read-only.
Inputs: no named parameters.
wg_overviewFlat overviewARead-onlyIdempotentInspect
Returns the manifest of the connected flat: wg (id, name, shareCode, createdAt), members (id, name, color) and currentMember (your memberId and name). Call it at the start of a task to resolve member names to the member ids that all other tools take. For balances, spending and open items use dashboard_get; to list the other flats of the account use wg_list. Read-only; any member may call it.
Inputs: wgCode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 65 tools
Descriptions carefully distinguish many pairs, but the large set still has several close boundaries: settlement_preview/settlement_commit/cash_payment_record/expense_split_settle, chat_messages/chat_unread/chat_mark_read, notes_list/note_comments, and inventory_consume/inventory_update. An agent can usually choose correctly after reading the long descriptions, but the names alone do not make the choices obvious.
Most tools follow a snake_case verb_noun style, but resource naming varies between plural list tools and singular get/update tools, such as chores_list vs chore_get and events_list vs event_create. A few names are not verb-first, like cash_payment_record and expense_split_settle, but the overall pattern remains readable.
With 65 tools, the server is far beyond the recommended 3-15 range and crosses the 50+ threshold where tool discovery and selection become unwieldy. Flat management is broad, but this surface should be split into smaller domain-focused servers.
Core read/create/update workflows are covered across many domains, but several described lifecycle operations are missing from the actual tool surface: shopping_remove, expense_delete, event_delete, note_delete/comment delete, absence_delete, invite_revoke, recurring_delete, member_update/wg_update, inventory_remove, and reminder_send. These gaps will block common delete, revoke, admin, and reminder workflows.
Maintenance
Related MCP Connectors
Hosted memory for AI assistants: a knowledge graph over MCP with OAuth. Hosted in Germany.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Persistent memory for AI assistants — one shared, OAuth-secured vault for every MCP client.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for Splitwise that enables users to manage shared expenses, friends, and groups directly through AI assistants. It allows for creating, deleting, and listing expenses while providing tools to track net balances and group debts.8MIT
- FlicenseNot gradedqualityBmaintenanceSelf-hosted household finance app for shared expenses, budgets, investments, loans, and zakat, exposing MCP tools for AI agents to manage finances via natural language.3-
- AlicenseAqualityBmaintenanceEnables AI assistants to securely interact with rental management data (leases, rent status, tenant records, tax filings) through a per-user OAuth 2.0 authenticated MCP server, with human-in-the-loop for sensitive actions.5AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceA self-hosted remote MCP server that gives AI assistants read, organize and optional send access to mail, calendars, tasks and contacts across many IMAP, Gmail, CalDAV, CardDAV and Google accounts behind one authenticated endpoint.2Apache 2.0