home / mcp / aave liquidation mcp server

Aave Liquidation MCP Server

MCP server for analyzing Aave V3 liquidation opportunities

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "clumsynonono-aave-liquidation-mcp": {
      "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",
        "HEALTH_FACTOR_THRESHOLD": "1.05"
      }
    }
  }
}

You want a focused, read-only MCP server that analyzes Aave V3 liquidation opportunities on Ethereum mainnet and makes its insights available to AI assistants. This server computes health factors, analyzes liquidation risk, tracks positions, and provides price and protocol data without executing any transactions. It is designed to be integrated with an MCP client to run analyses across single or multiple addresses, delivering actionable insights for strategy development and risk assessment.

How to use

You can use this MCP server through an MCP client to query health factors, analyze liquidation opportunities, view asset-by-asset positions, and perform batch checks across multiple addresses. Start by ensuring your client is configured to connect to the local MCP server, then execute the available tools to fetch health data, perform risk assessments, or run batch analyses. The server provides results in structured JSON that you can feed into AI workflows, dashboards, or risk reports.

How to install

Prerequisites you need before installation are straightforward:

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

Step-by-step setup process you should follow exactly:

# 1) Clone or download the project

# 2) Install dependencies
npm install

# 3) Configure environment variables
cp .env.example .env
# Edit .env and add your Ethereum RPC URL on the ETHEREUM_RPC_URL line

# 4) Build the project
npm run build

# 5) Start in development mode (optional for local testing)
npm run dev

Configuration and runtime details

The MCP server is designed to be run locally and connected to an MCP client. You provide the Ethereum RPC URL and optional health factor threshold in environment variables. The configuration snippet shown below demonstrates how you connect the local MCP server to your Claude Desktop setup.

{
  "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"
      }
    }
  }
}

Environment and startup details

Expose the Ethereum RPC endpoint to the MCP server. You can also adjust the health factor warning threshold if you want earlier risk warnings.

# 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

Starting the MCP server with Claude Desktop

Add the MCP server configuration to your Claude Desktop config so the client can launch and communicate with the local server. The following example shows the expected JSON structure to declare the local stdio server.

{
  "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"
      }
    }
  }
}

Troubleshooting and tips

If you encounter connection issues, verify that the Ethereum RPC URL is reachable from your environment and that the MCP server process is running. Check that the path to the built index.js file is correct and that the environment variable ETHEREUM_RPC_URL is set in the process environment used by the MCP client.

Security and best practices

Keep your RPC URL secret and avoid exposing it in publicly accessible logs. Use separate RPC endpoints for development and production, and prefer endpoints with higher rate limits for batch analyses. Do not attempt to execute liquidations from the MCP server; this tool is designed for read-only analysis and research.

Notes

The MCP server focuses on analysis and education for DeFi liquidation mechanics and risk assessment. It is intended to be integrated with AI assistants for data-driven insights rather than transaction execution.

Available tools

get_user_health

Fetch health factor, collateral, debt, and basic account risk metrics for a single address.

analyze_liquidation

Analyze a given address for liquidation risk with a detailed breakdown and potential profit estimates.

get_user_positions

Retrieve detailed collateral and debt positions for an address.

get_aave_reserves

List all Aave V3 reserves with configuration such as LTV and liquidation thresholds.

get_asset_price

Query current USD price for a specific asset from the Aave oracle.

get_protocol_status

Obtain protocol status and current block information.

batch_check_addresses

Batch analyze up to 20 addresses for liquidation opportunities with summary results.

validate_address

Validate Ethereum address formatting.