You Need A Budget (YNAB) MCP

Instructions

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}",
          )
      ]

• src/ynab_mcp_server/tool_models.py:233-251 (schema)

  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",
  }