Aave Liquidation MCP

🚀 Aave Liquidation MCP Server

This is a Model Context Protocol (MCP) server designed for analyzing Aave V3 liquidation opportunities on the Ethereum mainnet. It allows AI assistants like Claude to interact with Aave protocol data, monitor user positions, and identify potential liquidation opportunities.

✨ Features

🔍 Health Factor Monitoring

• Real-time health factor calculation: Calculate the health factor for any Ethereum address in real time.
• Multi-threshold risk detection:
  • HEALTHY: Health Factor > 1.05
  • AT_RISK: 1.0 < HF < 1.05
  • LIQUIDATABLE: HF < 1.0
• Automatic risk level classification: Classify risk levels (HIGH, MEDIUM, LOW) automatically.
• Account summary: Provide an account summary including collateral, debt, and borrow capacity.

💰 Liquidation Analysis

• Detailed position breakdown: Break down positions by asset in detail.
• Profit estimation: Estimate potential profits from liquidation opportunities.
• Collateral and debt composition analysis: Analyze the composition of collateral and debt.
• Liquidation bonus calculation: Calculate the liquidation bonus for each specific asset.
• Risk scoring: Score risks based on multiple factors.

📊 Position Tracking

• Complete portfolio view: Offer a comprehensive view of the portfolio for any address.
• Asset-by-asset breakdown: Break down deposits and borrows for each asset.
• Collateral status: Show the collateral status of each asset.
• Real-time balance updates: Update balances in real time from on-chain data.

🔢 Batch Operations

• Check up to 20 addresses simultaneously: Check up to 20 addresses at once.
• Parallel processing: Use parallel processing for faster results.
• Summary statistics: Provide summary statistics such as the number of liquidatable and at-risk addresses.
• Bulk risk assessment: Conduct bulk risk assessment for portfolio monitoring.

💲 Price & Protocol Data

• Real-time asset prices: Obtain real-time asset prices from the Aave oracle.
• USD-denominated values: Present all positions in USD-denominated values.
• Reserve (asset) listing: List all reserves (assets) with full configuration.
• LTV, liquidation thresholds, and bonuses: Provide LTV, liquidation thresholds, and bonuses for each asset.
• Current block number: Display the 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: It provides data and insights rather than executing transactions.
• AI-First Design: It is optimized for integration with AI assistants via the MCP protocol.
• Educational Value: It helps users understand the mechanics of DeFi liquidation.
• Research Tool: It is 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.

💻 Usage Examples

Basic Usage

Once configured with Claude Desktop, you can ask questions like:

• Single Address Queries:
  • "Check the health factor for address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  • "Are there any liquidation opportunities for this address?"
  • "What are the collateral positions for this user?"
  • "Analyze this address for liquidation risk: 0x..."
• Batch Operations:
  • "Check these 5 addresses for liquidation risk: [paste addresses]"
  • "Monitor multiple wallets and tell me which ones are at risk"
  • "Compare liquidation risk across these addresses"
• Protocol Queries:
  • "Show me all available assets in Aave V3"
  • "What's the current price of WETH in Aave?"
  • "What are the liquidation parameters for USDC?"
  • "What's the current block number?"
• Validation:
  • "Is this a valid Ethereum address: 0x123..."
  • "Validate these addresses before I check them"

Advanced Usage

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

Setup Verification

After installing and configuring the server, restart Claude Desktop and verify it's working: Ask Claude:

Can you check the Aave protocol status?

Claude will use the get_protocol_status tool and should return something like:

{
  "protocol": "Aave V3",
  "network": "Ethereum Mainnet",
  "blockNumber": 18500000,
  "poolAddress": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
  "status": "operational"
}

Understanding the Data

Health Factor

• > 1.0: The position is healthy.
• < 1.05: The position is at risk (warning).
• < 1.0: The position can be liquidated.

Risk Levels

• HIGH: Health factor < 1.0 (immediately liquidatable).
• MEDIUM: Health factor between 1.0 and 1.02.
• LOW: Health factor between 1.02 and 1.05.

Liquidation Bonus

When a position is liquidated, the liquidator receives a bonus (typically 5 - 10% depending on the asset). The potentialProfit field estimates this bonus.

Development

Project Structure

aave-liquidation-mcp/
├── src/
│   ├── index.ts           # MCP server implementation
│   ├── aave-client.ts     # Aave protocol interaction logic
│   ├── constants.ts       # Contract addresses and ABIs
│   └── types.ts           # TypeScript type definitions
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── .env                   # Configuration

Building

npm run build

Development Mode

npm run dev

This will watch for file changes and recompile automatically.

🔧 Technical Details

Aave V3 Contracts (Ethereum Mainnet)

• Pool: 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2
• Pool Data Provider: 0x7B4EB56E7CD4b454BA8ff71E4518426369a138a3
• Oracle: 0x54586bE62E3c3580375aE3723C145253060Ca0C2

Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• ethers: Ethereum library for contract interaction
• dotenv: Environment variable management

Limitations

• Mainnet Only: Currently, it only supports the Ethereum mainnet.
• Read-Only: It does not execute liquidations but only analyzes opportunities.
• Rate Limits: It is subject to the rate limits of your RPC provider.
• Gas Estimation: Profit calculations are estimates and do not account for gas costs.

Future Enhancements

• [ ] Multi-chain support (Arbitrum, Optimism, Polygon, Base)
• [ ] Historical liquidation data and analytics
• [ ] Advanced profit calculations including gas costs
• [ ] Webhook notifications for at-risk positions
• [ ] Integration with The Graph for historical queries
• [ ] Support for Aave V2 alongside V3

Resources

• Aave V3 Documentation
• Model Context Protocol
• Liquidation Guide

📄 License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This tool is for educational and research purposes only. Liquidating positions on DeFi protocols involves financial risk. Always do your own research and understand the risks before participating in DeFi activities.