Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:13-21 (registration)

  Tool registration for 'get_accounts' in the MCP tool definitions array, including name, description, and input schema (empty object, no required parameters)

  {
    name: 'get_accounts',
    description: 'Get all financial accounts from Monarch Money',
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
    },
  },

• src/tools.ts:206-207 (handler)

  Route handler in executeTool switch statement that dispatches to getAccounts() method when tool name is 'get_accounts'

  case 'get_accounts':
    return await this.getAccounts();

• src/tools.ts:248-263 (handler)

  Implementation of getAccounts() handler method that calls the API, formats the response with success/data/summary structure, and handles errors

  private async getAccounts(): Promise<any> {
    try {
      const accounts = await this.api.getAccounts();
      return {
        success: true,
        data: accounts,
        summary: `Found ${accounts?.length || 0} accounts`,
      };
    } catch (error) {
      throw new Error(
        `Failed to get accounts: ${
          error instanceof Error ? error.message : 'Unknown error'
        }`
      );
    }
  }

• src/monarch-api.ts:180-270 (handler)

  Underlying MonarchMoneyAPI.getAccounts() method that executes GraphQL query to fetch accounts with detailed fields and handles authentication errors

  async getAccounts(): Promise<Account[]> {
    const query = `
          query GetAccounts {
            accounts {
              ...AccountFields
              __typename
            }
            householdPreferences {
              id
              accountGroupOrder
              __typename
            }
          }
  
          fragment AccountFields on Account {
            id
            displayName
            syncDisabled
            deactivatedAt
            isHidden
            isAsset
            mask
            createdAt
            updatedAt
            displayLastUpdatedAt
            currentBalance
            displayBalance
            includeInNetWorth
            hideFromList
            hideTransactionsFromReports
            includeBalanceInNetWorth
            includeInGoalBalance
            dataProvider
            dataProviderAccountId
            isManual
            transactionsCount
            holdingsCount
            manualInvestmentsTrackingMethod
            order
            logoUrl
            type {
              display
              group
              name
              __typename
            }
            subtype {
              name
              display
              __typename
            }
            credential {
              id
              updateRequired
              disconnectedFromDataProviderAt
              dataProvider
              institution {
                id
                plaidInstitutionId
                name
                status
                __typename
              }
              __typename
            }
            institution {
              id
              name
              primaryColor
              url
              __typename
            }
            __typename
          }
    `;
  
    try {
      const data: any = await this.graphQLClient.request(query);
      return data.accounts || [];
    } 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 accounts: ${error.message}`);
    }
  }

• src/monarch-api.ts:10-29 (schema)

  TypeScript interface definition for Account type with properties like id, displayName, currentBalance, type, subtype, and institution

  export interface Account {
    id: string;
    mask: string | null;
    displayName: string;
    currentBalance: number;
    includeInNetWorth: boolean;
    type: {
      name: string;
      group: string;
      display: string;
    };
    subtype: {
      name: string;
      display: string;
    };
    institution?: {
      id: string;
      name: string;
    };
  }