YNAB MCP Server

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    category_id: The category ID to analyze
    start_year: Starting year (e.g., 2020)
    num_years: Number of years to compare (default: 5)
    include_graph: Include terminal graph visualization (default: True)

Returns:
    JSON string with year-over-year comparison including totals, changes, percentage changes, and optional graph

Implementation Reference

• src/ynab_mcp/server.py:316-340 (registration)

  MCP tool registration for compare_spending_by_year. Thin wrapper that gets YNABClient singleton and calls its method, returning JSON.

  @mcp.tool()
  async def compare_spending_by_year(
      budget_id: str,
      category_id: str,
      start_year: int,
      num_years: int = 5,
      include_graph: bool = True,
  ) -> str:
      """Compare spending for a category across multiple years.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          category_id: The category ID to analyze
          start_year: Starting year (e.g., 2020)
          num_years: Number of years to compare (default: 5)
          include_graph: Include terminal graph visualization (default: True)
  
      Returns:
          JSON string with year-over-year comparison including totals, changes, percentage changes, and optional graph
      """
      client = get_ynab_client()
      result = await client.compare_spending_by_year(
          budget_id, category_id, start_year, num_years, include_graph
      )
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:987-1083 (handler)

  Core handler implementation in YNABClient. Fetches transactions via YNAB API since start_year, filters by category_id and date range, aggregates yearly spending totals, computes year-over-year absolute and percentage changes, calculates average, and optionally generates a terminal graph using _generate_graph.

  async def compare_spending_by_year(
      self,
      budget_id: str,
      category_id: str,
      start_year: int,
      num_years: int = 5,
      include_graph: bool = True,
  ) -> dict[str, Any]:
      """Compare spending for a category across multiple years.
  
      Args:
          budget_id: The budget ID or 'last-used'
          category_id: The category ID to analyze
          start_year: Starting year (e.g., 2020)
          num_years: Number of years to compare (default: 5)
          include_graph: Include terminal graph visualization (default: True)
  
      Returns:
          Year-over-year comparison with totals and percentage changes
      """
      try:
          # Get all transactions since the start year
          since_date = f"{start_year}-01-01"
          end_year = start_year + num_years - 1
          until_date = f"{end_year}-12-31"
  
          url = f"{self.api_base_url}/budgets/{budget_id}/transactions"
          params = {"since_date": since_date}
  
          result = await self._make_request_with_retry("get", url, params=params)
  
          txn_data = result["data"]["transactions"]
  
          # Aggregate by year
          yearly_totals = {}
          for year in range(start_year, end_year + 1):
              yearly_totals[str(year)] = 0
  
          for txn in txn_data:
              # Filter by category and date range
              if txn.get("category_id") != category_id:
                  continue
              if txn["date"] > until_date:
                  continue
  
              year = txn["date"][:4]
              if year in yearly_totals:
                  amount = txn["amount"] / 1000 if txn.get("amount") else 0
                  yearly_totals[year] += amount
  
          # Calculate year-over-year changes
          comparisons = []
          years_sorted = sorted(yearly_totals.keys())
  
          for i, year in enumerate(years_sorted):
              year_data = {
                  "year": year,
                  "total_spent": yearly_totals[year],
              }
  
              if i > 0:
                  prev_year = years_sorted[i - 1]
                  prev_total = yearly_totals[prev_year]
                  change = yearly_totals[year] - prev_total
  
                  if prev_total != 0:
                      percent_change = (change / abs(prev_total)) * 100
                  else:
                      percent_change = 0 if change == 0 else float("inf")
  
                  year_data["change_from_previous"] = change
                  year_data["percent_change"] = percent_change
  
              comparisons.append(year_data)
  
          # Calculate overall statistics
          totals = [yearly_totals[year] for year in years_sorted]
          average_per_year = sum(totals) / len(totals) if totals else 0
  
          result_data = {
              "category_id": category_id,
              "years": f"{start_year}-{end_year}",
              "average_per_year": average_per_year,
              "yearly_comparison": comparisons,
          }
  
          # Add graph if requested
          if include_graph and yearly_totals:
              graph_data = [(year, yearly_totals[year]) for year in years_sorted]
              result_data["graph"] = self._generate_graph(
                  graph_data, f"Year-over-Year Comparison: {start_year}-{end_year}"
              )
  
          return result_data
      except Exception as e:
          raise Exception(f"Failed to compare spending by year: {e}") from e

• src/ynab_mcp/ynab_client.py:848-904 (helper)

  Helper method to generate ASCII terminal bar graph using termgraph library. Captures stdout to return graph as string. Used in compare_spending_by_year for visual year-over-year comparison.

  def _generate_graph(self, data: list[tuple], title: str = "") -> str:
      """Generate a terminal graph using termgraph.
  
      Args:
          data: List of (label, value) tuples
          title: Graph title
  
      Returns:
          String containing the terminal graph
      """
      if not data:
          return ""
  
      # Capture termgraph output
      old_stdout = sys.stdout
      sys.stdout = StringIO()
  
      try:
          # Prepare data for termgraph
          labels = [label for label, _ in data]
          values = [[abs(value)] for _, value in data]
  
          # Configure termgraph
          args = {
              "stacked": False,
              "width": 50,
              "format": "{:.2f}",
              "suffix": "",
              "no_labels": False,
              "color": None,
              "vertical": False,
              "different_scale": False,
              "calendar": False,
              "start_dt": None,
              "custom_tick": "",
              "delim": "",
              "verbose": False,
              "label_before": False,
              "histogram": False,
              "no_values": False,
          }
  
          # Print title
          if title:
              print(f"\n{title}")
              print("=" * len(title))
  
          # Generate graph
          tg.chart(colors=[], data=values, args=args, labels=labels)
  
          # Get the output
          output = sys.stdout.getvalue()
          return output
  
      finally:
          sys.stdout = old_stdout