Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:370-388 (handler)

  The main handler implementation for get_budget_summary tool. Calls api.getBudgets() and returns budget information with a success status, data, and summary message.
  private async getBudgetSummary(): Promise<any> { try { const budgets = await this.api.getBudgets(); return { success: true, data: budgets, summary: `Retrieved budget information for ${ budgets?.length || 0 } categories`, }; } catch (error) { throw new Error( `Failed to get budget summary: ${ error instanceof Error ? error.message : 'Unknown error' }` ); } }
• src/tools.ts:85-93 (registration)

  Tool registration definition for get_budget_summary with name, description, and input schema (no required parameters).
  name: 'get_budget_summary', description: 'Get current budget summary showing planned vs actual spending', inputSchema: { type: 'object', properties: {}, required: [], }, },
• src/tools.ts:218-219 (registration)

  Case statement in executeTool switch that routes 'get_budget_summary' tool calls to the getBudgetSummary() handler method.
  case 'get_budget_summary': return await this.getBudgetSummary();
• src/monarch-api.ts:52-58 (schema)

  Budget interface defining the structure of budget data returned by the API, including id, name, amount, spent, and remaining fields.
  export interface Budget { id: string; name: string; amount: number; spent: number; remaining: number; }
• src/monarch-api.ts:342-406 (helper)

  Underlying API implementation that fetches budget data from Monarch Money via GraphQL query, calculating planned vs actual spending for the current month.
  async getBudgets(): Promise<Budget[]> { const query = ` query Common_GetJointPlanningData($startDate: Date!, $endDate: Date!) { budgetSystem budgetData(startMonth: $startDate, endMonth: $endDate) { monthlyAmountsByCategory { category { id name __typename } monthlyAmounts { month plannedAmount actualAmount __typename } __typename } __typename } } `; const now = new Date(); const startDate = new Date(now.getFullYear(), now.getMonth(), 1) .toISOString() .split('T')[0]; const endDate = new Date(now.getFullYear(), now.getMonth() + 1, 0) .toISOString() .split('T')[0]; try { const data: any = await this.graphQLClient.request(query, { startDate, endDate, }); const categoryData = data.budgetData?.monthlyAmountsByCategory || []; return categoryData.map((catData: any) => { const currentMonth = catData.monthlyAmounts?.find( (ma: any) => ma.month === startDate.substring(0, 7) ); return { id: catData.category?.id, name: catData.category?.name, amount: currentMonth?.plannedAmount || 0, spent: currentMonth?.actualAmount || 0, remaining: (currentMonth?.plannedAmount || 0) - (currentMonth?.actualAmount || 0), }; }); } catch (error: any) { if ( error.message.includes('401') || error.message.includes('unauthorized') ) { throw new Error( 'Authentication failed. Please check your MONARCH_TOKEN environment variable.' ); } throw new Error(`Failed to get budgets: ${error.message}`); } }