Aave Liquidation MCP Server

Instructions

Implementation Reference

• src/index.ts:399-480 (handler)

  Main handler for 'batch_check_addresses' tool execution. Validates input addresses, calls batchAnalyzeLiquidation on AaveClient, processes results into summary statistics, and returns formatted JSON response.
  case 'batch_check_addresses': { const addresses = args?.addresses as string[]; if (!Array.isArray(addresses) || addresses.length === 0) { throw new McpError( ErrorCode.InvalidParams, 'addresses parameter is required and must be a non-empty array' ); } if (addresses.length > 20) { throw new McpError( ErrorCode.InvalidParams, 'Maximum 20 addresses allowed per batch request' ); } // Validate all addresses first const invalidAddresses = addresses.filter( (addr) => typeof addr !== 'string' || !aaveClient.isValidAddress(addr) ); if (invalidAddresses.length > 0) { throw new McpError( ErrorCode.InvalidParams, `Invalid Ethereum addresses: ${invalidAddresses.join(', ')}` ); } const results = await aaveClient.batchAnalyzeLiquidation(addresses); // Calculate summary statistics let liquidatable = 0; let atRisk = 0; let healthy = 0; let failed = 0; const formattedResults = results.map((r) => { // Count statistics if (r.error) { failed++; } else if (r.opportunity?.riskLevel === 'HIGH') { liquidatable++; } else if (r.opportunity) { atRisk++; } else { healthy++; } return { address: r.address, status: r.error ? 'ERROR' : r.opportunity ? r.opportunity.riskLevel === 'HIGH' ? 'LIQUIDATABLE' : 'AT_RISK' : 'HEALTHY', healthFactor: r.opportunity?.healthFactor || 'N/A', totalDebtUSD: r.opportunity?.totalDebtUSD || '0', riskLevel: r.opportunity?.riskLevel || 'NONE', error: r.error, }; }); const summary = { totalChecked: addresses.length, successful: addresses.length - failed, failed, liquidatable, atRisk, healthy, results: formattedResults, }; return { content: [ { type: 'text', text: JSON.stringify(summary, null, 2), }, ], }; }
• src/index.ts:129-146 (schema)

  Input schema definition for the batch_check_addresses tool, specifying an array of Ethereum addresses (max 20).
  { name: 'batch_check_addresses', description: 'Batch check multiple Ethereum addresses for liquidation opportunities. Returns a summary of all addresses with their health status.', inputSchema: { type: 'object', properties: { addresses: { type: 'array', items: { type: 'string', }, description: 'Array of Ethereum addresses to check (max 20 addresses)', }, }, required: ['addresses'], }, },
• src/index.ts:48-164 (registration)

  Registration of all tools including batch_check_addresses via the ListToolsRequestHandler.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { 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'], }, }, { name: 'analyze_liquidation', description: 'Analyze a user position for liquidation opportunity. Returns detailed information including collateral assets, debt assets, risk level, and potential profit.', inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Ethereum address to analyze (must be a valid address)', }, }, required: ['address'], }, }, { name: 'get_user_positions', description: 'Get detailed breakdown of a user collateral and debt positions across all Aave V3 assets.', inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Ethereum address to query', }, }, required: ['address'], }, }, { name: 'get_aave_reserves', description: 'Get list of all available reserves (assets) in Aave V3 protocol with their configuration.', inputSchema: { type: 'object', properties: {}, }, }, { name: 'get_asset_price', description: 'Get current price for a specific asset from Aave oracle.', inputSchema: { type: 'object', properties: { assetAddress: { type: 'string', description: 'Token contract address', }, }, required: ['assetAddress'], }, }, { name: 'get_protocol_status', description: 'Get general Aave V3 protocol status including current block number.', inputSchema: { type: 'object', properties: {}, }, }, { name: 'batch_check_addresses', description: 'Batch check multiple Ethereum addresses for liquidation opportunities. Returns a summary of all addresses with their health status.', inputSchema: { type: 'object', properties: { addresses: { type: 'array', items: { type: 'string', }, description: 'Array of Ethereum addresses to check (max 20 addresses)', }, }, required: ['addresses'], }, }, { name: 'validate_address', description: 'Validate if a string is a valid Ethereum address format.', inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Address string to validate', }, }, required: ['address'], }, }, ], }; });
• src/aave-client.ts:308-339 (helper)

  Core helper function batchAnalyzeLiquidation that concurrently analyzes multiple addresses for liquidation opportunities by calling analyzeLiquidationOpportunity on each.
  async batchAnalyzeLiquidation( addresses: string[] ): Promise<BatchAnalysisResult[]> { const results: BatchAnalysisResult[] = new Array(addresses.length); const concurrency = Math.min(5, addresses.length); let currentIndex = 0; const worker = async () => { while (true) { const idx = currentIndex++; if (idx >= addresses.length) { break; } const address = addresses[idx]; try { const opportunity = await this.analyzeLiquidationOpportunity(address); results[idx] = { address, opportunity }; } catch (error) { results[idx] = { address, opportunity: null, error: error instanceof Error ? error.message : String(error), }; } } }; await Promise.all(Array.from({ length: concurrency }, () => worker())); return results; }
• src/aave-client.ts:205-296 (helper)

  Supporting helper function analyzeLiquidationOpportunity used by batch_check to analyze single address positions, compute health factor, risk level, and estimated liquidation profit.
  async analyzeLiquidationOpportunity( userAddress: string ): Promise<LiquidationOpportunity | null> { const accountData = await this.getUserAccountData(userAddress); // Only return if liquidatable or at risk if (!accountData.isLiquidatable && !accountData.isAtRisk) { return null; } const { collateral, debt } = await this.getUserReserves(userAddress); // Calculate risk level const hf = parseFloat(accountData.healthFactorFormatted); let riskLevel: 'HIGH' | 'MEDIUM' | 'LOW'; if (hf < LIQUIDATION_THRESHOLD) { riskLevel = 'HIGH'; } else if (hf < 1.02) { riskLevel = 'MEDIUM'; } else { // 1.02 <= hf < WARNING_THRESHOLD (1.05) riskLevel = 'LOW'; } // Format values in USD (base is already in USD with 8 decimals from oracle) const totalCollateralUSD = ethers.formatUnits(accountData.totalCollateralBase, 8); const totalDebtUSD = ethers.formatUnits(accountData.totalDebtBase, 8); const availableBorrowsUSD = ethers.formatUnits(accountData.availableBorrowsBase, 8); // Calculate potential profit with actual liquidation bonus let potentialProfit = '0'; if (accountData.isLiquidatable) { const debtValue = parseFloat(totalDebtUSD); // Close factor: can liquidate up to 50% of debt const maxDebtByCloseFactor = debtValue * 0.5; // Fetch prices for collateral assets to avoid overstating profit const priceMap = collateral.length ? await this.getAssetsPrices(collateral.map((c) => c.asset)) : new Map<string, string>(); let bestEstimatedProfit = 0; for (const c of collateral) { const priceStr = priceMap.get(c.asset); const price = priceStr ? parseFloat(priceStr) : 0; if (!price) { continue; } // Convert collateral balance to USD using token decimals and oracle price (8 decimals) const collateralAmount = parseFloat(ethers.formatUnits(c.currentATokenBalance, c.decimals)); const collateralValueUSD = collateralAmount * price; // liquidationBonus is in bps, e.g. 10500 => 5% bonus const bonusPercentage = Math.max(0, Number(c.liquidationBonus) - 10000) / 10000; if (bonusPercentage <= 0) { continue; } // Debt that can be covered by this collateral considering bonus const maxDebtByCollateral = collateralValueUSD / (1 + bonusPercentage); // Actual liquidatable debt for this collateral const liquidatableDebt = Math.min(maxDebtByCloseFactor, maxDebtByCollateral, debtValue); const estimatedProfit = liquidatableDebt * bonusPercentage; if (estimatedProfit > bestEstimatedProfit) { bestEstimatedProfit = estimatedProfit; } } potentialProfit = bestEstimatedProfit.toFixed(2); } return { userAddress, healthFactor: accountData.healthFactorFormatted, totalCollateralUSD, totalDebtUSD, availableBorrowsUSD, liquidationThreshold: parseFloat( ethers.formatUnits(accountData.currentLiquidationThreshold, 4) ), collateralAssets: collateral, debtAssets: debt, potentialProfit, riskLevel, gasWarning: 'Profit calculation does not include Gas costs. Actual profit will be lower.', }; }