Aave Liquidation MCP Server

A Model Context Protocol (MCP) server for analyzing Aave V3 liquidation opportunities on Ethereum mainnet. This tool enables AI assistants like Claude to interact with Aave protocol data, monitor user positions, and identify liquidation opportunities.

Features

Health Factor Monitoring

• Real-time health factor calculation for any Ethereum address
• Multi-threshold risk detection:
  • HEALTHY: Health Factor > 1.05
  • AT_RISK: 1.0 < HF < 1.05
  • LIQUIDATABLE: HF < 1.0
• Automatic risk level classification (HIGH, MEDIUM, LOW)
• Account summary with collateral, debt, and borrow capacity

Liquidation Analysis

• Detailed position breakdown by asset
• Profit estimation for liquidation opportunities
• Collateral and debt composition analysis
• Liquidation bonus calculation (asset-specific)
• Risk scoring based on multiple factors

Position Tracking

• Complete portfolio view for any address
• Asset-by-asset breakdown of deposits and borrows
• Collateral status for each asset
• Real-time balance updates from on-chain data

Batch Operations

• Check up to 20 addresses simultaneously
• Parallel processing for faster results
• Summary statistics (liquidatable count, at-risk count, etc.)
• Bulk risk assessment for portfolio monitoring

Price & Protocol Data

• Real-time asset prices from Aave oracle
• USD-denominated values for all positions
• Reserve (asset) listing with full configuration
• LTV, liquidation thresholds, and bonuses by asset
• Current block number for data verification

What Makes This Different

Unlike existing liquidation bots that execute liquidations, this MCP server focuses on:

• Analysis over Execution: Provides data and insights rather than executing transactions
• AI-First Design: Optimized for integration with AI assistants via MCP protocol
• Educational Value: Helps users understand DeFi liquidation mechanics
• Research Tool: Useful for strategy development and risk analysis

Installation

Prerequisites

• Node.js 18 or higher
• An Ethereum RPC endpoint (Alchemy, Infura, QuickNode, or your own node)

Setup

1. Clone or download this repository

2. Install dependencies:

   npm install
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env and add your Ethereum RPC URL
   

4. Build the project:

   npm run build
   

Configuration

Environment Variables

Create a .env file in the project root:

# Required: Ethereum RPC endpoint
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY

# Optional: Health factor warning threshold (default: 1.05)
HEALTH_FACTOR_THRESHOLD=1.05

Getting an RPC Endpoint

You can get a free Ethereum RPC endpoint from:

• Alchemy: https://www.alchemy.com/ (Recommended, 300M compute units/month free)
• Infura: https://www.infura.io/ (100k requests/day free)
• QuickNode: https://www.quicknode.com/ (Free tier available)

MCP Configuration

Add this server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aave-liquidation": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/aave-liquidation-mcp/build/index.js"],
      "env": {
        "ETHEREUM_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with the actual path to your installation.

Quick Demo Scripts

Test the server functionality without MCP configuration:

# Get current ETH price
npm run demo:price

# View all Aave reserves (categorized)
npm run demo:reserves

# Run comprehensive connection test
npm run test:real-data

Available Tools (8 Total)

1. get_user_health

Get health factor and account data for a specific address.

Input:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

Output:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "healthFactor": "1.234",
  "totalCollateralUSD": "150000.00",
  "totalDebtUSD": "100000.00",
  "availableBorrowsUSD": "20000.00",
  "liquidationThreshold": "0.85",
  "ltv": "0.80",
  "isLiquidatable": false,
  "isAtRisk": false,
  "status": "HEALTHY"
}

2. analyze_liquidation

Analyze a position for liquidation opportunity with detailed breakdown.

Input:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

Output:

{
  "userAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "healthFactor": "0.98",
  "totalCollateralUSD": "150000.00",
  "totalDebtUSD": "140000.00",
  "riskLevel": "HIGH",
  "potentialProfit": "7000.00",
  "collateralAssets": [...],
  "debtAssets": [...]
}

3. get_user_positions

Get detailed collateral and debt positions for an address.

Input:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

4. get_aave_reserves

Get list of all available Aave V3 reserves with their configurations.

Input: None required

Output: List of all reserves with LTV, liquidation threshold, liquidation bonus, etc.

5. get_asset_price

Get current USD price for a specific asset from Aave oracle.

Input:

{
  "assetAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
}

6. get_protocol_status

Get Aave V3 protocol status and current block number.

Input: None required

7. batch_check_addresses

Check multiple addresses at once for liquidation opportunities (max 20 addresses per request).

Input:

{
  "addresses": [
    "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "0xAnotherAddress...",
    "0xYetAnotherAddress..."
  ]
}

Output:

{
  "totalChecked": 3,
  "liquidatable": 1,
  "atRisk": 1,
  "healthy": …