Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:324-368 (handler)

  The actual implementation of get_spending_by_category that fetches transactions, filters for expenses (negative amounts), groups spending by category, sorts by amount descending, and returns the spending breakdown with totals.

  private async getSpendingByCategory(
    startDate: string,
    endDate: string
  ): Promise<any> {
    try {
      const transactions = await this.api.getTransactions({
        startDate,
        endDate,
        limit: 5000,
      });
  
      const categorySpending: Record<string, number> = {};
  
      transactions?.forEach((transaction: Transaction) => {
        if (transaction.amount < 0) {
          // Expenses are negative
          const category = transaction.category?.name || 'Uncategorized';
          categorySpending[category] =
            (categorySpending[category] || 0) + Math.abs(transaction.amount);
        }
      });
  
      const sortedCategories = Object.entries(categorySpending)
        .sort(([, a], [, b]) => b - a)
        .map(([category, amount]) => ({ category, amount }));
  
      return {
        success: true,
        data: sortedCategories,
        summary: `Spending breakdown for ${
          Object.keys(categorySpending).length
        } categories from ${startDate} to ${endDate}`,
        totalSpent: Object.values(categorySpending).reduce(
          (sum, amount) => sum + amount,
          0
        ),
      };
    } catch (error) {
      throw new Error(
        `Failed to get spending by category: ${
          error instanceof Error ? error.message : 'Unknown error'
        }`
      );
    }
  }

• src/tools.ts:65-83 (schema)

  Tool schema definition for get_spending_by_category, including name, description, and inputSchema with required startDate and endDate parameters (YYYY-MM-DD format).

  {
    name: 'get_spending_by_category',
    description:
      'Get spending breakdown by category for a specific time period',
    inputSchema: {
      type: 'object',
      properties: {
        startDate: {
          type: 'string',
          description: 'Start date in YYYY-MM-DD format',
        },
        endDate: {
          type: 'string',
          description: 'End date in YYYY-MM-DD format',
        },
      },
      required: ['startDate', 'endDate'],
    },
  },

• src/tools.ts:215-216 (registration)

  Switch case registration in executeTool method that routes 'get_spending_by_category' tool calls to the getSpendingByCategory implementation with startDate and endDate arguments.

  case 'get_spending_by_category':
    return await this.getSpendingByCategory(args.startDate, args.endDate);