Bilanz

Get the user's total balance as of a date (defaults to today). Balance is computed from transactions and converted to the user's base currency (or the currency you specify). Args: as_of: Date YYYY-MM-DD to compute balance as of. Defaults to today. currency: Currency to express the balance in. Defaults to the user's profile base currency. account_id: Restrict balance to this account UUID. account_ids: Restrict balance to these accounts (comma-separated UUIDs). account_type: Restrict to accounts of this type: cash, credit_card, debit_card, or savings. Returns {{ as_of, currency, balance }}.

Get the balance per account as of a date (defaults to today). Each account shows its native balance and the balance converted to the base currency. Args: as_of: Date YYYY-MM-DD. Defaults to today. currency: Base currency for conversion. Defaults to user's profile currency. account_id: Restrict to this account UUID. account_ids: Restrict to these accounts (comma-separated UUIDs). account_type: Restrict to accounts of this type: cash, credit_card, debit_card, or savings. Returns {{ as_of, currency, total, accounts: [...] }}.

Get balance history for charts or lists. Shows how the total (or per-account) balance evolved over time. Args: date_from: Series start date YYYY-MM-DD (required). date_to: Series end date YYYY-MM-DD (required). period: Granularity: 'day', 'week', or 'month'. Defaults to 'month'. account_id: Optional UUID to filter to a single account. account_ids: Optional comma-separated UUIDs to filter to multiple accounts. currency: Base currency for conversion. Defaults to user's profile currency. Returns {{ currency, period, points: [{{ date, balance }}, ...] }}.

Get balance history with per-account breakdown for drill-down charts. Args: date_from: Series start date YYYY-MM-DD (required). date_to: Series end date YYYY-MM-DD (required). period: Granularity: 'day', 'week', or 'month'. Defaults to 'month'. account_id: Optional UUID to filter to a single account. account_ids: Optional comma-separated UUIDs to filter to multiple accounts. currency: Base currency for conversion. Defaults to user's profile currency. Returns points with per-account balances and percentage breakdown.

Get a budget by ID with computed spending for the active period. Args: budget_id: Budget UUID. period_offset: Shift recurrent budget period (-1 previous, 1 next).

Get spending breakdown grouped by accounts, categories, tags, or concepts. Args: budget_id: Budget UUID. group_by: 'accounts', 'categories', 'tags', or 'concepts'. period_offset: Shift recurrent budget period.

Get historical cashflow series grouped by time period. Ideal for charts showing income and expense trends over time. Args: date_from: Series start date YYYY-MM-DD (required). date_to: Series end date YYYY-MM-DD (required). period: Grouping granularity: 'day', 'week', or 'month'. Defaults to 'month'. account_id: Filter by account UUID. account_ids: Filter by multiple accounts (comma-separated UUIDs). category_id: Filter to one category UUID. category_ids: Filter to multiple categories (comma-separated UUIDs). currency: If provided, filter to this currency only. If omitted, amounts are FX-converted to the user's base currency. amount_min: Minimum amount filter. amount_max: Maximum amount filter. source: Transaction source filter. Returns a list of points with period_start (bucket end date), income, expense, and net.

Get income, expense, and net cashflow totals for a period. Provide EITHER period OR date_from + date_to. Args: period: 'day', 'week', 'month', or 'year'. date_from: Start date YYYY-MM-DD. date_to: End date YYYY-MM-DD. period_offset: Shift period window (-1 previous, 1 next). Only with period. type: Category type filter: 'income' or 'expense'. category_id: Filter to a single category UUID. category_ids: Filter to multiple categories (comma-separated UUIDs). account_id: Filter by account UUID. account_ids: Filter by multiple accounts (comma-separated UUIDs). currency: Filter by currency code. amount_min: Minimum amount filter. amount_max: Maximum amount filter. source: Transaction source filter. tag_ids: Comma-separated tag UUIDs. concept_ids: Comma-separated concept UUIDs. Returns {{ income, expense, total }} all as decimal strings.

Get all categories for the authenticated user. Args: type: Optional filter. Use 'income', 'expense', or 'transfer' to return only categories of that type. Leave empty for all categories. Returns a list with id, name, type, icon, color, and ownership info.

Get categories with their net transaction amounts for a time period. Provide EITHER period OR date_from + date_to (period takes precedence). Args: period: Predefined period: 'day', 'week', 'month', or 'year'. date_from: Start date YYYY-MM-DD (use with date_to when period is not set). date_to: End date YYYY-MM-DD (use with date_from when period is not set). period_offset: Shift period window (-1 previous, 1 next). Only with period. type: Filter by category type: 'income' or 'expense'. category_id: Restrict to a single category UUID. category_ids: Restrict to multiple categories (comma-separated UUIDs). account_id: Filter transactions by account UUID. account_ids: Filter transactions by multiple accounts (comma-separated UUIDs). currency: Filter transactions by currency code. amount_min: Minimum transaction amount. amount_max: Maximum transaction amount. source: Filter by transaction source. tag_ids: Comma-separated tag UUIDs. concept_ids: Comma-separated concept UUIDs. full_list: If True (default), include categories with 0 transactions. If False, return only categories that have matching transactions. Returns categories with transaction_amount (net-signed) and transaction_count.

Get a single category by its ID. The category must belong to the authenticated user. Provide category_id as a UUID string.

Get concept breakdown within a specific category for a period or date range. Transactions without a concept are grouped into an "Uncategorized" bucket. Args: category_id: Category UUID to drill into. period: 'day', 'week', 'month', or 'year' (or use date_from/date_to). date_from: Start date YYYY-MM-DD. date_to: End date YYYY-MM-DD. period_offset: Shift period window when using period. account_id: Filter by account UUID. account_ids: Filter by multiple accounts (comma-separated UUIDs). currency: Filter by currency code. amount_min, amount_max, source: Optional transaction filters. tag_ids: Comma-separated tag UUIDs. concept_ids: Comma-separated concept UUIDs.

Get a single concept by its ID. The concept must belong to the authenticated user. Provide concept_id as a UUID string.

Get all concepts (transaction labels/descriptions) for the authenticated user. Concepts are reusable descriptions that can be attached to transactions. Returns a list with id, name, and ownership info.

Compare current period cashflow vs the previous equivalent period. Useful for detecting trends: 'this month vs last month'. Provide EITHER period OR date_from + date_to. Args: period: 'week', 'month', or 'year'. date_from: Custom period start YYYY-MM-DD. date_to: Custom period end YYYY-MM-DD. period_offset: Shift predefined period (-1 previous, 1 next). account_id: Filter by account UUID. account_ids: Filter by multiple accounts (comma-separated UUIDs). category_id: Filter to one category UUID. category_ids: Filter to multiple categories (comma-separated UUIDs). currency: Filter by currency. amount_min: Minimum amount. amount_max: Maximum amount. source: Transaction source filter. Returns current_period, previous_period metrics, and a summary with difference, percentage_change, and trend ('up'|'down'|'flat').

Get the most recent transactions for the authenticated user. Args: limit: Number of transactions to return. Must be one of: 5, 10, 20, 50, 100. Defaults to 10. Returns the most recent transactions ordered by date descending.

Get a single tag by its ID. The tag must belong to the authenticated user. Provide tag_id as a UUID string.

Get all tags for the authenticated user. Tags can be attached to transactions for flexible categorization. Returns a list with id, name, and ownership info.

Get a single transaction by its ID. The transaction must belong to the authenticated user. Provide transaction_id as a UUID string.

Get the profile of the currently authenticated user. Returns name, email, currency, language, and other profile fields. Requires a completed profile and current privacy acceptance in the Bilanz app (see MCP access errors when sign-up or notice acceptance is pending).

List archived and expired budgets for the authenticated user.

List expense transactions excluded from a budget in the active period. Args: budget_id: Budget UUID. period_offset: Shift recurrent budget period. account_id: Optional account filter UUID. category_id: Optional category filter UUID. tag_id: Optional tag filter UUID. concept_id: Optional concept filter UUID. date_from: Optional start date YYYY-MM-DD (requires date_to). date_to: Optional end date YYYY-MM-DD (requires date_from).

List expense transactions counted toward a budget in the active period. Args: budget_id: Budget UUID. period_offset: Shift recurrent budget period. account_id: Optional account filter UUID. category_id: Optional category filter UUID. tag_id: Optional tag filter UUID. concept_id: Optional concept filter UUID. date_from: Optional start date YYYY-MM-DD (requires date_to). date_to: Optional end date YYYY-MM-DD (requires date_from).

List active budgets for the authenticated user.

Reassign all transactions from one category to another. Use before deleting a category that still has transactions. Both categories must belong to the user and share the same type.

Partially update a single field on the authenticated user's profile. Exactly one field must be provided. Email cannot be changed.

Atomically delete a standalone transaction and create a transfer pair. Cannot be used on a transfer leg.

Atomically delete a transfer pair and create a single income/expense transaction. The new transaction is tagged with source 'mcp'.

Search transactions with optional filters. All parameters are optional. Combine them to narrow results. Args: account_id: Filter by account UUID. account_ids: Filter by multiple accounts (comma-separated UUIDs). category_id: Filter by category UUID. category_ids: Filter by multiple categories (comma-separated UUIDs). type: 'income', 'expense', or 'transfer'. currency: Currency code, e.g. 'MXN', 'USD'. date_from: Start date in YYYY-MM-DD format (use with date_to). date_to: End date in YYYY-MM-DD format (use with date_from). period: Predefined period: 'day', 'week', 'month', or 'year'. Use EITHER period OR date_from/date_to, not both. period_offset: Shift period window (-1 previous, 1 next). Only with period. amount_min: Minimum transaction amount (decimal string, e.g. '100.00'). amount_max: Maximum transaction amount (decimal string, e.g. '5000.00'). source: Transaction source, e.g. 'manual'. tag_ids: Comma-separated tag UUIDs. concept_ids: Comma-separated concept UUIDs. has_concept: True for transactions with a concept, False for without. Returns paginated results with total count and transaction list.

Update an account owned by the authenticated user. Only provided fields are changed.

Update an account's initial balance and anchor date. Both fields are required. The anchor date must be on or before the account's first transaction.

Update budget fields, scope, or exclusions. Budget type cannot be changed. Scope/exclusion fields accept comma-separated UUID lists for junction add/remove.

Update a category owned by the authenticated user.

Update a concept owned by the authenticated user.

Update a tag owned by the authenticated user.

Update a transaction owned by the authenticated user. Only provided fields are changed. Pass tags_json as '[]' to clear all tags.

Update both legs of a transfer pair. Only provided fields are changed.

Fully update the authenticated user's profile. All core fields are required except optional phone, currency, language, profile_image, and is_registered.