Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:390-433 (handler)

  The main handler function searchTransactions() that implements the search logic - fetches transactions, filters by query (merchant, notes, plaidName), minAmount, maxAmount, and returns limited results
  private async searchTransactions(args: any): Promise<any> { try { const limit = args.limit || 50; const transactions = await this.api.getTransactions({ limit: 1000 }); // Get more to search through let filteredTransactions = transactions || []; if (args.query) { const query = args.query.toLowerCase(); filteredTransactions = filteredTransactions.filter( (t: Transaction) => t.plaidName?.toLowerCase().includes(query) || t.notes?.toLowerCase().includes(query) || t.merchant?.name?.toLowerCase().includes(query) ); } if (args.minAmount !== undefined) { filteredTransactions = filteredTransactions.filter( (t: Transaction) => Math.abs(t.amount) >= args.minAmount ); } if (args.maxAmount !== undefined) { filteredTransactions = filteredTransactions.filter( (t: Transaction) => Math.abs(t.amount) <= args.maxAmount ); } const results = filteredTransactions.slice(0, limit); return { success: true, data: results, summary: `Found ${results.length} transactions matching criteria`, }; } catch (error) { throw new Error( `Failed to search transactions: ${ error instanceof Error ? error.message : 'Unknown error' }` ); } }
• src/tools.ts:95-121 (registration)

  Tool definition/registration in getToolDefinitions() specifying name, description, and inputSchema with properties for query, minAmount, maxAmount, and limit
  name: 'search_transactions', description: 'Search transactions by description, merchant, or amount', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query for transaction description or merchant', }, minAmount: { type: 'number', description: 'Minimum transaction amount', }, maxAmount: { type: 'number', description: 'Maximum transaction amount', }, limit: { type: 'number', description: 'Number of results to return (default: 50)', default: 50, }, }, required: [], }, },
• src/tools.ts:221-222 (registration)

  Switch case in executeTool() that routes 'search_transactions' tool calls to the searchTransactions handler method
  case 'search_transactions': return await this.searchTransactions(args);
• src/monarch-api.ts:272-340 (helper)

  Helper API method getTransactions() that fetches transactions from Monarch Money GraphQL API with optional filters for limit, accountId, startDate, and endDate
  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 type definition that defines the structure of transaction objects including id, amount, date, plaidName, notes, merchant, and account fields used throughout the search implementation
  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; }; }