lunchmoney-mcp

Instructions

Implementation Reference

• src/index.ts:101-142 (registration)

  Registration of the 'get-budget-summary' tool, including input schema with Zod validation for dates and the inline asynchronous handler that fetches budgets and returns a formatted text summary or error.

  this.server.tool(
      "get-budget-summary",
      "Get budget summary for a specific time period",
      {
          start_date: z.string().describe("Start date (YYYY-MM-DD, should be start of month)"),
          end_date: z.string().describe("End date (YYYY-MM-DD, should be end of month)"),
      },
      async ({ start_date, end_date }) => {
          try {
              const budgets = await this.fetchBudgets(start_date, end_date);
              
              if (!budgets.length) {
                  return {
                      content: [
                          {
                              type: "text",
                              text: "No budget data found for the specified period.",
                          },
                      ],
                  };
              }
  
              return {
                  content: [
                      {
                          type: "text",
                          text: this.formatBudgetSummary(budgets),
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Error fetching budget data: ${error}`,
                      },
                  ],
              };
          }
      }
  );

• src/index.ts:262-275 (helper)

  Helper function 'fetchBudgets' that makes an API call to retrieve budget data for the specified date range from Lunchmoney API.

  private async fetchBudgets(start_date: string, end_date: string): Promise<Budget[]> {
      const response = await fetch(`${API_BASE}/budgets?start_date=${start_date}&end_date=${end_date}`, {
          headers: {
              Authorization: `Bearer ${this.token}`,
              Accept: "application/json",
          }
      });
  
      if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      return await response.json() as Budget[];
  }

• src/index.ts:277-313 (helper)

  Helper function 'formatBudgetSummary' that processes the budget data into a detailed text summary including category info, monthly spending vs budget, remaining amounts, and recurring expenses.

  private formatBudgetSummary(budgets: Budget[]): string {
      let summary: string[] = [];
  
      for (const budget of budgets) {
          const categoryHeader = `Category: ${budget.category_name}${budget.category_group_name ? ` (${budget.category_group_name})` : ''}`;
          let budgetInfo: string[] = [categoryHeader];
  
          // Add monthly data
          Object.entries(budget.data).forEach(([date, data]) => {
              const monthData = [
                  `\nMonth: ${date}`,
                  `Transactions: ${data.num_transactions || 0}`,
                  `Spending: ${data.spending_to_base?.toFixed(2) || '0.00'} ${data.budget_currency?.toUpperCase() || 'USD'}`,
              ];
  
              if (data.budget_amount) {
                  monthData.push(`Budget: ${data.budget_amount.toFixed(2)} ${data.budget_currency?.toUpperCase() || 'USD'}`);
                  const remainingBudget = (data.budget_amount - (data.spending_to_base || 0)).toFixed(2);
                  monthData.push(`Remaining: ${remainingBudget} ${data.budget_currency?.toUpperCase() || 'USD'}`);
              }
  
              budgetInfo.push(monthData.join('\n'));
          });
  
          // Add recurring items if any
          if (budget.recurring && budget.recurring.list && budget.recurring.list.length > 0) {
              budgetInfo.push('\nRecurring Items:');
              budget.recurring.list.forEach(item => {
                  budgetInfo.push(`- ${item.payee}: ${item.amount} ${item.currency.toUpperCase()}`);
              });
          }
  
          summary.push(budgetInfo.join('\n'));
      }
  
      return summary.join('\n\n---\n\n');
  }

• src/index.ts:77-80 (schema)

  Type definition for BudgetParams matching the tool's input parameters.

  interface BudgetParams {
      start_date: string;
      end_date: string;
  }

• src/index.ts:61-76 (schema)

  Type definition for Budget, describing the structure of budget data returned by the API.

  interface Budget {
      category_name: string;
      category_id: number;
      category_group_name: string | null;
      group_id: number | null;
      is_group: boolean | null;
      is_income: boolean;
      exclude_from_budget: boolean;
      exclude_from_totals: boolean;
      data: Record<string, BudgetData>;
      config: BudgetConfig | null;
      order: number;
      archived: boolean;
      recurring: Recurring | null;
  }