Monarch Money MCP Server

Instructions

Implementation Reference

• src/tools.ts:598-619 (handler)

  The main handler function getPortfolio that executes the get_portfolio tool logic. It calls the API, processes the response, and returns a formatted result with success status and summary.

  private async getPortfolio(
    startDate?: string,
    endDate?: string
  ): Promise<any> {
    try {
      const portfolio = await this.api.getPortfolio(startDate, endDate);
  
      return {
        success: true,
        data: portfolio,
        summary: `Retrieved portfolio summary with ${
          portfolio?.aggregateHoldings?.edges?.length || 0
        } holdings`,
      };
    } catch (error) {
      throw new Error(
        `Failed to get portfolio: ${
          error instanceof Error ? error.message : 'Unknown error'
        }`
      );
    }
  }

• src/tools.ts:182-200 (registration)

  Tool registration for 'get_portfolio' including name, description, and inputSchema with optional startDate and endDate parameters.

  {
    name: 'get_portfolio',
    description:
      'Get current investment portfolio summary, including holdings and performance',
    inputSchema: {
      type: 'object',
      properties: {
        startDate: {
          type: 'string',
          description: 'Start date in YYYY-MM-DD format',
        },
        endDate: {
          type: 'string',
          description: 'End date in YYYY-MM-DD format',
        },
      },
      required: [],
    },
  },

• src/tools.ts:240-241 (registration)

  Switch case handler that routes 'get_portfolio' tool name to the getPortfolio method with arguments.

  case 'get_portfolio':
    return await this.getPortfolio(args.startDate, args.endDate);

• src/monarch-api.ts:60-119 (schema)

  Portfolio interface schema defining the return type structure with performance data, aggregate holdings, and nested objects.

  interface Portfolio {
    performance: {
      totalValue: number;
      totalBasis: number;
      totalChangePercent: number;
      totalChangeDollars: number;
      oneDayChangePercent: number;
      historicalChart: {
        date: string;
        returnPercent: number;
      }[];
      benchmarks: {
        security: {
          id: string;
          ticker: string;
          name: string;
          oneDayChangePercent: number;
        };
        historicalChart: {
          date: string;
          returnPercent: number;
        }[];
      }[];
    };
    aggregateHoldings: {
      edges: {
        node: {
          id: string;
          quantity: number;
          basis: number;
          totalValue: number;
          securityPriceChangeDollars: number | null;
          securityPriceChangePercent: number | null;
          lastSyncedAt: string | null;
          holdings: {
            id: string;
            type: string;
            typeDisplay: string;
            name: string;
            ticker: string | null;
            closingPrice: number | null;
            closingPriceUpdatedAt: string | null;
            quantity: number;
            value: number;
            account: Account;
          }[];
          security: {
            id: string;
            name: string;
            ticker: string | null;
            currentPrice: number | null;
            currentPriceUpdatedAt: string | null;
            closingPrice: number | null;
            type: string;
            typeDisplay: string;
          };
        };
      }[];
    };
  }

• src/monarch-api.ts:478-594 (helper)

  API layer getPortfolio method that constructs and executes the GraphQL query to fetch portfolio data from Monarch Money.

  async getPortfolio(startDate?: string, endDate?: string): Promise<Portfolio> {
    const query = `
      query GetPortfolio($portfolioInput: PortfolioInput) {
        portfolio(input: $portfolioInput) {
          performance {
            totalValue
            totalBasis
            totalChangePercent
            totalChangeDollars
            oneDayChangePercent
            historicalChart {
              date
              returnPercent
              __typename
            }
            benchmarks {
              security {
                id
                ticker
                name
                oneDayChangePercent
                __typename
              }
              historicalChart {
                date
                returnPercent
                __typename
              }
              __typename
            }
            __typename
          }
          aggregateHoldings {
            edges {
              node {
                id
                quantity
                basis
                totalValue
                securityPriceChangeDollars
                securityPriceChangePercent
                lastSyncedAt
                holdings {
                  id
                  type
                  typeDisplay
                  name
                  ticker
                  closingPrice
                  closingPriceUpdatedAt
                  quantity
                  value
                  account {
                    id
                    mask
                    icon
                    logoUrl
                    institution {
                      id
                      name
                      __typename
                    }
                    type {
                      name
                      display
                      __typename
                    }
                    subtype {
                      name
                      display
                      __typename
                    }
                    displayName
                    currentBalance
                    __typename
                  }
                  __typename
                }
                security {
                  id
                  name
                  ticker
                  currentPrice
                  currentPriceUpdatedAt
                  closingPrice
                  type
                  typeDisplay
                  __typename
                }
                __typename
              }
              __typename
            }
            __typename
          }
          __typename
        }
      }
    `;
  
    try {
      const data: any = await this.graphQLClient.request(query, {
        portfolioInput: { startDate, endDate },
      });
      return data.portfolio;
    } 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 portfolio: ${error.message}`);
    }
  }