list-transactions
Fetch and analyze transactions for a specific account or month to review spending patterns. Provides detailed insights for budgeting and financial tracking in YNAB.
Instructions
List transactions for a specific account or an entire month. Use this to investigate spending patterns identified in the financial overview.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | The ID of the account to fetch transactions for. | |
| budget_id | No | The ID of the budget. If not provided, the default budget will be used. | |
| limit | No | The maximum number of transactions to return. | |
| month | No | The month to fetch transactions for (YYYY-MM-DD format). | |
| since_date | No | The starting date for transactions (YYYY-MM-DD). Only valid if 'account_id' is provided. |
Implementation Reference
- src/ynab_mcp_server/server.py:198-258 (handler)Main execution logic for the 'list-transactions' tool: validates input using ListTransactionsInput, fetches transactions via ynab_client based on account_id or month parameters, applies filters and limits, formats a text response with transaction details.elif name == "list-transactions": args = ListTransactionsInput.model_validate(arguments or {}) budget_id = await _get_budget_id(args.model_dump()) limit = int(args.limit) if args.limit is not None else None if args.account_id and not args.month: transactions = await ynab_client.get_transactions( budget_id=budget_id, account_id=args.account_id, since_date=args.since_date, limit=limit, ) header = f"Here are the latest transactions for account {args.account_id}:" elif args.month: since_date = args.month if args.account_id: transactions = await ynab_client.get_transactions( budget_id=budget_id, account_id=args.account_id, since_date=since_date, ) header = f"Here are the transactions for account {args.account_id} in {args.month}:" else: transactions = await ynab_client.get_monthly_transactions( budget_id=budget_id, month=since_date, ) header = f"Here are the transactions for {args.month}:" if transactions: # Filter transactions to the specified month transactions = [ t for t in transactions if str(t.var_date).startswith(since_date[:7]) ] if limit: transactions = transactions[:limit] else: # This case should now be primarily for account_id with since_date transactions = await ynab_client.get_transactions( budget_id=budget_id, account_id=args.account_id, since_date=args.since_date, limit=limit, ) header = f"Here are the latest transactions for account {args.account_id}:" if not transactions: return [types.TextContent(type="text", text="No transactions found.")] transaction_list = "\n".join( f"- {t.var_date}: {t.payee_name or 'N/A'} | " f"{t.category_name or 'N/A'} | {t.amount / 1000:.2f} (ID: {t.id})" for t in transactions ) return [ types.TextContent( type="text", text=f"{header}\n{transaction_list}", ) ]
- Pydantic model ListTransactionsInput defining the input schema for the tool, with fields for budget_id (inherited), account_id, month, since_date, limit, and validation ensuring either account_id or month is provided.class ListTransactionsInput(BudgetIdInput): account_id: Optional[str] = Field(None, description="The ID of the account to fetch transactions for.") month: Optional[str] = Field(None, description="The month to fetch transactions for (YYYY-MM-DD format).") since_date: Optional[str] = Field( None, description="The starting date for transactions (YYYY-MM-DD). Only valid if 'account_id' is provided." ) limit: Optional[float] = Field( None, description="The maximum number of transactions to return." ) @model_validator(mode='before') @classmethod def check_exclusive_fields(cls, values): if not values.get('account_id') and not values.get('month'): raise ValueError('Either "account_id" or "month" must be provided.') if values.get('month') and values.get('since_date'): raise ValueError('"since_date" is not applicable when "month" is provided.') return values
- src/ynab_mcp_server/server.py:59-63 (registration)Tool registration in handle_list_tools(), defining name, description, and inputSchema for 'list-transactions'.types.Tool( name="list-transactions", description="List transactions for a specific account or an entire month. Use this to investigate spending patterns identified in the financial overview.", inputSchema=ListTransactionsInput.model_json_schema(), ),
- src/ynab_mcp_server/server.py:30-40 (registration)Includes 'list-transactions' in the set of read-only tools, which are always available even in read-only mode.READ_ONLY_TOOLS = { "list-budgets", "list-accounts", "list-transactions", "list-categories", "list-payees", "list-scheduled-transactions", "get-financial-overview", "get-month-info", "lookup-payee-locations", }