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;
    };
  }