archive_budget
ChatGPTArchive a budget so it no longer appears in the active list.
create_account
ChatGPTCreate a new account for the authenticated user. Args: name: Account display name. type: 'cash', 'credit_card', 'debit_card', or 'savings'. currency: Currency code, e.g. MXN or USD. initial_balance: Starting balance as decimal string. initial_balance_date: Anchor date YYYY-MM-DD for initial balance. color: Optional hex color, e.g. #3B82F6.
create_budget
ChatGPTCreate a budget with optional scope filters and exclusions. Args: name: Budget name. type: 'recurrent' or 'one_time'. currency: Currency code, e.g. MXN. amount: Budget limit as decimal string. start_date: Start date YYYY-MM-DD. recurrence: Required for recurrent budgets: daily, weekly, monthly, quarterly, semester, yearly. end_date: Optional end date YYYY-MM-DD. include_transfers: Whether transfer transactions count toward spending. scope_account_ids: Comma-separated account UUIDs (empty = all). scope_category_ids: Comma-separated category UUIDs (empty = all). scope_tag_ids: Comma-separated tag UUIDs (empty = all). scope_concept_ids: Comma-separated concept UUIDs (empty = all). exclude_tag_ids: Comma-separated tag UUIDs to exclude from spending. exclude_concept_ids: Comma-separated concept UUIDs to exclude from spending.
create_category
ChatGPTCreate a new category for the authenticated user. Args: name: Category name. type: 'income' or 'expense'. Defaults to 'expense'. icon: Optional icon identifier. color: Optional hex color.
create_concept
ChatGPTCreate a new concept for the authenticated user.
create_tag
ChatGPTCreate a new tag for the authenticated user.
create_transaction
ChatGPTCreate a new income or expense transaction. Transactions created via MCP are tagged with source 'mcp' (not 'manual'). Args: account_id: Account UUID. category_id: Category UUID. type: 'income' or 'expense'. amount: Decimal string, e.g. '150.00'. date: Transaction date YYYY-MM-DD. concept_id: Link to existing concept UUID (optional). concept_name: Create or link concept by name (optional). concept_color: Concept color when creating by name (optional). tags_json: JSON array of tag objects, e.g. [{"id": "uuid"}] or [{"name": "Recurring", "color": "#fff"}].
create_transfer
ChatGPTCreate a transfer between two accounts owned by the user. Args: from_account_id: Source account UUID. to_account_id: Destination account UUID. amount: Decimal string. date: Transfer date YYYY-MM-DD. concept_id, concept_name, concept_color: Optional concept link/create. tags_json: Optional JSON array of tag objects.
get_account
ChatGPTGet a single account by its ID. The account must belong to the authenticated user. Provide account_id as a UUID string.
get_accounts
ChatGPTGet all accounts belonging to the authenticated user. Args: account_type: Optional filter: 'cash', 'credit_card', 'debit_card', or 'savings'. Returns a list of accounts with their id, name, type, currency, color, initial_balance, and creation dates.
get_balance
ChatGPTGet 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_balance_accounts
ChatGPTGet 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
ChatGPTGet 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_by_accounts
ChatGPTGet 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_budget
ChatGPTGet 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_budget_grouped
ChatGPTGet 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_cashflow_history
ChatGPTGet 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_cashflow_summary
ChatGPTGet 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_categories
ChatGPTGet 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_summary
ChatGPTGet 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_category
ChatGPTGet a single category by its ID. The category must belong to the authenticated user. Provide category_id as a UUID string.
get_category_concepts_summary
ChatGPTGet 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_concept
ChatGPTGet a single concept by its ID. The concept must belong to the authenticated user. Provide concept_id as a UUID string.
get_concepts
ChatGPTGet 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.
get_period_comparison
ChatGPTCompare 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_recent_transactions
ChatGPTGet 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_tag
ChatGPTGet a single tag by its ID. The tag must belong to the authenticated user. Provide tag_id as a UUID string.
get_tags
ChatGPTGet 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_transaction
ChatGPTGet a single transaction by its ID. The transaction must belong to the authenticated user. Provide transaction_id as a UUID string.
get_user_profile
ChatGPTGet 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_budgets
ChatGPTList archived and expired budgets for the authenticated user.
list_budget_excluded_transactions
ChatGPTList 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_budget_transactions
ChatGPTList 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_budgets
ChatGPTList active budgets for the authenticated user.
migrate_category_transactions
ChatGPTReassign 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.
patch_user_profile
ChatGPTPartially update a single field on the authenticated user's profile. Exactly one field must be provided. Email cannot be changed.
replace_transaction_with_transfer
ChatGPTAtomically delete a standalone transaction and create a transfer pair. Cannot be used on a transfer leg.
replace_transfer_with_transaction
ChatGPTAtomically delete a transfer pair and create a single income/expense transaction. The new transaction is tagged with source 'mcp'.
search_transactions
ChatGPTSearch 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_account
ChatGPTUpdate an account owned by the authenticated user. Only provided fields are changed.
update_account_initial_balance
ChatGPTUpdate 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
ChatGPTUpdate budget fields, scope, or exclusions. Budget type cannot be changed. Scope/exclusion fields accept comma-separated UUID lists for junction add/remove.
update_category
ChatGPTUpdate a category owned by the authenticated user.
update_concept
ChatGPTUpdate a concept owned by the authenticated user.
update_tag
ChatGPTUpdate a tag owned by the authenticated user.
update_transaction
ChatGPTUpdate a transaction owned by the authenticated user. Only provided fields are changed. Pass tags_json as '[]' to clear all tags.
update_transfer
ChatGPTUpdate both legs of a transfer pair. Only provided fields are changed.
update_user_profile
ChatGPTFully update the authenticated user's profile. All core fields are required except optional phone, currency, language, profile_image, and is_registered.