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