# aave-liquidation-mcp
## 基本信息
- Slug: `clumsynonono-aave-liquidation-mcp`
- Source: modelscope
- Publisher: @clumsynonono/aave-liquidation-mcp
- Categories: blockchain / 金融 / monitoring
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@clumsynonono/aave-liquidation-mcp
## 简介
暂无描述。
## 安装提示

```bash
npm install
```

## MCP Server 详情

# 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:
   ```bash
   npm install
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env and add your Ethereum RPC URL
   ```

4. Build the project:
   ```bash
   npm run build
   ```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# 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`

```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:

```bash
# 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:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "addresses": [
    "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "0xAnotherAddress...",
    "0xYetAnotherAddress..."
  ]
}
```

**Output:**
```json
{
  "totalChecked": 3,
  "liquidatable": 1,
  "atRisk": 1,
  "healthy": …