MCP Tool Reference

These are the tools your MCP client can call once you’ve connected to https://api.kualia.com/mcp. Names and parameters match exactly what the server registers. The same catalog powers the in-app AI Assistant. See MCP overview for how to connect, and the per-client guides (ChatGPT, Claude, Claude Code, Cursor, Perplexity) for client-specific setup.

Workspaces & accounts

Tool	What it does	Key params
`kualia_list_workspaces`	Lists the workspaces the authenticated user can access. Call this only when switching workspaces explicitly.	none
`kualia_export_workspace_data`	Creates a ZIP archive with CSV files for categories and targets, monthly plan data, bank accounts, and transactions. Credit-card categories use their bank account name, plan rows are ordered by `year_month`, and Ready-to-Assign movements use `Ready to Assign` as their category name. Returns a download URL that expires after 24 hours. Split transactions use one row per movement, linked by `transaction_id`, `movement_index`, and `movement_count`.	`workspaceId?`
`kualia_list_bank_accounts`	Lists every bank account with name, type, on-budget flag, currency, current balance, and closed flag.	`workspaceId?`, `includeClosed?`
`kualia_create_bank_account`	Creates a manual (unlinked) account from a `name` and `accountType`. `banking_`/`credit_` are on-budget; `investment_`/`loan_` are off-budget. Optionally seeds an opening balance.	`name` (required), `accountType` (required), `initialBalance?` + `initialBalanceDate?`, `workspaceId?`
`kualia_close_bank_account`	Closes an account non-destructively: reconciles it, marks it closed, disconnects any link, and keeps all transactions for history. Use instead of delete when the account has activity.	`bankAccountId` (required), `workspaceId?`
`kualia_delete_bank_account`	Deletes an account. Only succeeds when the account has no transactions; otherwise it refuses and you should close it instead. Also removes a credit account’s linked category.	`bankAccountId` (required), `workspaceId?`

Transactions

Tool	What it does	Key params
`kualia_list_transactions`	Lists transactions for a single month, with splits expanded to one row per movement. Each row carries a `url` linking to the transaction in the web app.	`yearMonth` (required), `workspaceId?`, `accountId?`, `categoryId?`, `type?`, `limit?` (default 500, max 1000)
`kualia_create_transactions`	Batch-creates regular or transfer rows (mix freely). Regular rows can be categorized, uncategorized, or sent directly to Ready to Assign. They are deduped against existing transactions on the same account and land as Needs Review. Up to 200 per call.	`transactions[]` (required), `bankAccountId?`, `forceInsert?`, `workspaceId?`
`kualia_update_transactions`	Batch-updates existing transactions: date, amount, category, movements, merchant, notes, account, status, review status, even type conversion. Up to 200 per call.	`updates[]` (required), `workspaceId?`
`kualia_delete_transactions`	Soft-deletes by id, reversing balance and budget side effects. Transfer pairs are deleted together. Up to 200 per call.	`transactionIds[]` (required), `workspaceId?`
`kualia_restore_transactions`	Undeletes soft-deleted transactions, re-applying balance and budget side effects. Transfer pairs are restored together. Up to 200 per call.	`transactionIds[]` (required), `workspaceId?`
`kualia_list_recurring_transactions`	Lists subscription, bill, and recurring-income templates with merchant, expected amount, and calculated next due date.	`status?` (`active` \| `inactive`, default `active`), `workspaceId?`

Creating transactions

For a regular, single-movement transaction, pass amount and choose one of:

categoryId to categorize it.
readyToAssign: true to treat it as income for Ready to Assign. This creates a movement with no category.
Neither field to leave it uncategorized or let Kualia apply rules and suggestions.

{
  "bankAccountId": "bank_account_checking",
  "transactions": [
    {
      "merchantName": "Payroll",
      "amount": "1200.00",
      "date": "2026-06-15",
      "readyToAssign": true,
      "notes": "June paycheck"
    }
  ]
}

Do not combine readyToAssign: true with categoryId on the same transaction or movement. For split transactions, pass movements and put readyToAssign: true on the specific movement that should go to Ready to Assign.

Categories & groups

Tool	What it does	Key params
`kualia_list_category_groups`	Lists category groups with their nested categories.	`workspaceId?`
`kualia_create_categories`	Batch-creates categories inside an existing group. Up to 50 per call. Per-row failures (duplicate names, unknown group) don’t abort the batch.	`categories[]` (required, with `name` + `categoryGroupId`), `workspaceId?`
`kualia_update_categories`	Batch-updates category `name`, `categoryGroupId`, or `iconName`. Up to 50 per call.	`updates[]` (required, with `categoryId`), `workspaceId?`
`kualia_archive_categories`	Archive (`isArchived: true`) or unarchive (`false`) categories in bulk. System and credit-card categories are rejected. All-or-nothing per call. Up to 50.	`categoryIds[]` (required), `isArchived` (required), `workspaceId?`
`kualia_reorder_categories`	Custom rearrangement. Places categories at exact top-to-bottom positions, including cross-group moves. Use only for arbitrary orderings.	`groups[]` (required, with `categoryGroupId` + `orderedCategoryIds`), `workspaceId?`
`kualia_sort_categories`	Server-side sort by `name_asc`/`name_desc`, `target_due_date_asc`/`_desc`, or `created_asc`/`_desc`. Sorts one group or every group.	`sortBy` (required), `categoryGroupId?`, `workspaceId?`
`kualia_create_category_groups`	Batch-creates groups (`type: 'expense'`). Up to 10 per call.	`groups[]` (required, with `name` + `type`), `workspaceId?`
`kualia_update_category_groups`	Batch-updates group `name` (and `type` back to `expense` if needed). Credit-card groups cannot be converted. Up to 10 per call.	`updates[]` (required, with `categoryGroupId`), `workspaceId?`
`kualia_archive_category_groups`	Archive (soft-delete) or restore groups in bulk. Group must be empty to archive. Credit-card groups can’t be archived. Up to 10 per call.	`categoryGroupIds[]` (required), `isArchived` (required), `workspaceId?`
`kualia_reorder_category_groups`	Custom rearrangement. Sets the top-to-bottom order of groups in the workspace.	`orderedCategoryGroupIds[]` (required), `workspaceId?`
`kualia_sort_category_groups`	Server-side sort by `name_asc`/`name_desc` or `created_asc`/`created_desc`.	`sortBy` (required), `workspaceId?`

Budgets & targets

Tool	What it does	Key params
`kualia_set_category_assigned_amount`	Sets the absolute assigned amount for one category-month (single mode) or many (bulk mode). Overwrites the existing assignment; it’s not a delta. Positive funds the category, negative pulls money back to Ready to Assign.	Single: `categoryId` + `yearMonth` + `assignedAmount`. Bulk: `updates[]`. Plus `workspaceId?`.
`kualia_get_envelope_month_status`	Returns one month of envelope status (assigned, activity, available) with assignment guidance (`remainingToAssign`, `underfundedAmount`, `assignmentNeeded`). Filter to a single category or group by id or name.	`yearMonth` (required), `currentDate` (required, YYYY-MM-DD), `categoryId?` \| `categoryName?` \| `groupId?` \| `groupName?`, `workspaceId?`
`kualia_list_category_targets`	Lists every category’s target definition (type, amount, frequency, due date, etc.) for categories that have targets enabled.	`workspaceId?`
`kualia_create_category_target`	Creates a target on a category that doesn’t have one. Types: `recurring`, `recurring_rollover`, `maintain_balance`, `one_time`. Credit-card categories are rejected.	`categoryId`, `targetType`, `amount` (all required); plus `frequency?`, `frequencyInterval?`, `dayOfWeek?`, `dueDay?`, `firstDueDate?`, `targetDate?`, `monthlyContribution?`, `targetBalance?`, `workspaceId?`
`kualia_update_category_target`	Updates an existing target. Nullable fields accept `null` to clear (`monthlyContribution`, `targetBalance`, `targetDate`, `dayOfWeek`, `dueDay`).	`categoryId` (required); same target fields as `create_category_target`, all optional; plus `workspaceId?`
`kualia_delete_category_target`	Disables the target on a category. Preserves the underlying settings so it can be re-enabled later. Idempotent.	`categoryId` (required), `workspaceId?`

Reports

Tool	What it does	Key params
`kualia_get_monthly_summary`	The canonical “how much did I spend, save, or earn” report. Per-month `income`, `spending`, `savings`, `savingsRate`, plus `byCategory` and `byGroup` spending breakdowns. Already excludes credit-card and loan transfer mechanics; use this instead of summing other reports.	`yearMonth?` xor `monthsBack?` (default 6, max 24); `currentYearMonth?`, `workspaceId?`
`kualia_get_spending_report`	Gross inflow and outflow activity by category, group, and merchant for a single month or range. An entity can appear in both directions; prefer `get_monthly_summary` for clean spending, income, and savings totals.	`yearMonth?` xor `monthsBack?`; `currentYearMonth?`, `workspaceId?`
`kualia_get_income_summary`	Income and inflow summary for a month or range, sourced from pre-aggregated workspace data.	`yearMonth?` xor `monthsBack?` (default 1); `currentYearMonth?`, `workspaceId?`
`kualia_get_category_rollup`	Multi-month per-category totals: total assigned, total inflow, total outflow.	`monthsBack?` (default 6, max 24), `currentYearMonth?`, `workspaceId?`
`kualia_get_account_balances_report`	Monthly account balance history across every account, with multi-currency support.	`monthsBack?`, `currentYearMonth?`, `workspaceId?`

Common parameters

workspaceId is optional on every tool and defaults to the user’s active workspace. Pass it explicitly only when the user has multiple workspaces and you need a non-default one. Get ids from kualia_list_workspaces.
yearMonth is YYYYMM (e.g. 202604 for April 2026). currentDate is YYYY-MM-DD.
Batch limits: transactions up to 200 per call; categories up to 50; category groups up to 10.
Money is encoded as a signed decimal string in the workspace currency, with at most minorUnit fractional digits (USD = 2 → "51.08"; JPY = 0 → "5108"; KWD = 3 → "5.108"). Each money-bearing response carries currencyCode, minorUnit, and amountEncoding: 'decimal_string'. Don’t scale by 100.

All tools respect per-workspace permissions. The server only returns and modifies data your account can access. Agent-driven updates also preserve a transaction’s reviewStatus: rows created or edited through MCP stay as Needs Review until you mark them reviewed in the app yourself.

Getting Started

Core Features

Apps & Platforms

MCP

API Reference

More

MCP Tool Reference

Workspaces & accounts

Transactions

Creating transactions

Categories & groups

Budgets & targets

Reports

Common parameters

​Workspaces & accounts

​Transactions

​Creating transactions

​Categories & groups

​Budgets & targets

​Reports

​Common parameters

Workspaces & accounts

Transactions

Creating transactions

Categories & groups

Budgets & targets

Reports

Common parameters