Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:293-322 (handler)

  Main handler implementation for get_transactions tool. Processes arguments (limit, accountId, startDate, endDate), calls the API method, and returns formatted response with success status, data, and summary.
  private async getTransactions(args: any): Promise<any> { try { const limit = Math.min(args.limit || 50, 500); const options: any = { limit }; if (args.accountId) { options.accountId = args.accountId; } if (args.startDate) { options.startDate = args.startDate; } if (args.endDate) { options.endDate = args.endDate; } const transactions = await this.api.getTransactions(options); return { success: true, data: transactions, summary: `Retrieved ${transactions?.length || 0} transactions`, }; } catch (error) { throw new Error( `Failed to get transactions: ${ error instanceof Error ? error.message : 'Unknown error' }` ); } }
• src/tools.ts:212-213 (registration)

  Tool registration in executeTool switch statement that routes 'get_transactions' tool name to the getTransactions handler method.
  case 'get_transactions': return await this.getTransactions(args);
• src/tools.ts:37-63 (schema)

  Tool schema definition including name, description, and inputSchema with properties for optional accountId, limit, startDate, and endDate parameters.
  name: 'get_transactions', description: 'Get recent transactions, optionally filtered by account, date range, or amount', inputSchema: { type: 'object', properties: { accountId: { type: 'string', description: 'Optional: Filter by specific account ID', }, limit: { type: 'number', description: 'Number of transactions to retrieve (default: 50, max: 500)', default: 50, }, startDate: { type: 'string', description: 'Start date in YYYY-MM-DD format', }, endDate: { type: 'string', description: 'End date in YYYY-MM-DD format', }, }, required: [], },
• src/monarch-api.ts:272-340 (handler)

  Underlying API method that executes GraphQL query to fetch transactions from Monarch Money API. Constructs query with filters and handles authentication errors.
  async getTransactions( options: { limit?: number; accountId?: string; startDate?: string; endDate?: string; offset?: number; } = {} ): Promise<Transaction[]> { const { limit = 100, accountId, startDate, endDate, offset = 0 } = options; const query = ` query GetTransactionsList($offset: Int, $limit: Int, $filters: TransactionFilterInput, $orderBy: TransactionOrdering) { allTransactions(filters: $filters) { totalCount results(offset: $offset, limit: $limit, orderBy: $orderBy) { id amount pending date plaidName notes category { id name __typename } merchant { name id __typename } account { id displayName } __typename } __typename } } `; const variables: any = { offset, limit, filters: {}, orderBy: 'date', }; if (accountId) variables.filters.accountId = accountId; if (startDate) variables.filters.startDate = startDate; if (endDate) variables.filters.endDate = endDate; try { const data: any = await this.graphQLClient.request(query, variables); return data.allTransactions?.results || []; } 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 transactions: ${error.message}`); } }
• src/monarch-api.ts:31-50 (schema)

  Transaction interface defining the data structure returned by the get_transactions tool, including id, amount, date, category, merchant, and account information.
  export interface Transaction { id: string; amount: number; date: string; plaidName?: string; notes?: string; pending?: boolean; category?: { id: string; name: string; }; merchant?: { id: string; name: string; }; account: { id: string; displayName: string; }; }