Aave Liquidation MCP Server

Instructions

Implementation Reference

• src/index.ts:51-65 (registration)

  Tool registration in listTools handler including name, description, and input schema

  {
    name: 'get_user_health',
    description:
      'Get health factor and account data for a specific Ethereum address on Aave V3. Returns collateral, debt, and liquidation status.',
    inputSchema: {
      type: 'object',
      properties: {
        address: {
          type: 'string',
          description: 'Ethereum address to check (must be a valid address)',
        },
      },
      required: ['address'],
    },
  },

• src/index.ts:174-227 (handler)

  MCP tool handler: validates input address, fetches account data via AaveClient, formats response with health factor, positions, and status

  case 'get_user_health': {
    const address = args?.address as string;
    if (!address || typeof address !== 'string') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'address parameter is required and must be a string'
      );
    }
  
    if (!aaveClient.isValidAddress(address)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid Ethereum address format'
      );
    }
  
    const accountData = await aaveClient.getUserAccountData(address);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              address: accountData.address,
              healthFactor: accountData.healthFactorFormatted,
              totalCollateralUSD: parseFloat(
                ethers.formatUnits(accountData.totalCollateralBase, 8)
              ).toFixed(2),
              totalDebtUSD: parseFloat(
                ethers.formatUnits(accountData.totalDebtBase, 8)
              ).toFixed(2),
              availableBorrowsUSD: parseFloat(
                ethers.formatUnits(accountData.availableBorrowsBase, 8)
              ).toFixed(2),
              liquidationThreshold: parseFloat(
                (Number(accountData.currentLiquidationThreshold) / 10000).toFixed(4)
              ),
              ltv: parseFloat((Number(accountData.ltv) / 10000).toFixed(4)),
              isLiquidatable: accountData.isLiquidatable,
              isAtRisk: accountData.isAtRisk,
              status: accountData.isLiquidatable
                ? 'LIQUIDATABLE'
                : accountData.isAtRisk
                ? 'AT_RISK'
                : 'HEALTHY',
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/aave-client.ts:58-76 (helper)

  Core helper function: queries Aave V3 Pool contract for user account data, computes formatted health factor and liquidation risk flags

  async getUserAccountData(userAddress: string): Promise<UserAccountData> {
    const data = await this.poolContract.getUserAccountData(userAddress);
  
    const healthFactorFormatted = ethers.formatUnits(data.healthFactor, 18);
    const healthFactorNumber = parseFloat(healthFactorFormatted);
  
    return {
      address: userAddress,
      totalCollateralBase: data.totalCollateralBase,
      totalDebtBase: data.totalDebtBase,
      availableBorrowsBase: data.availableBorrowsBase,
      currentLiquidationThreshold: data.currentLiquidationThreshold,
      ltv: data.ltv,
      healthFactor: data.healthFactor,
      healthFactorFormatted,
      isLiquidatable: healthFactorNumber < LIQUIDATION_THRESHOLD && healthFactorNumber > 0,
      isAtRisk: healthFactorNumber < WARNING_THRESHOLD && healthFactorNumber > 0,
    };
  }