# Ethereum Validator Queue MCP

An MCP server that tracks Ethereum’s validator activation and exit queues in real time, enabling AI agents to monitor staking dynamics and network participation trends.

![GitHub License](https://img.shields.io/github/license/kukapay/ethereum-validator-queue-mcp) 
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
![Status](https://img.shields.io/badge/status-active-brightgreen.svg)

## Features

- **Tools**:
  - `get_activation_queue`: Retrieves statistics about the Ethereum validator activation queue, including queue length, total active validators, entering validators' balance, and estimated wait time.
  - `get_exit_queue`: Retrieves statistics about the Ethereum validator exit queue, including queue length, total active validators, exiting validators' balance, and estimated wait time.
  - `get_validator_status`: Queries the status of a specific validator by its public key, providing details such as status, effective balance, activation epoch, and exit epoch.
- **Prompt**:
  - `analyze_queue`: A reusable prompt template for LLMs to analyze validator queue trends, including staking demand, impact on ETH price, and network security.

## Installation

### Prerequisites

- **Python**: Version 3.10 or higher
- **uv**: A fast and modern Python package manager ([installation instructions](https://docs.astral.sh/uv/))

### Setup

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/kukapay/ethereum-validator-queue-mcp.git
   cd ethereum-validator-queue-mcp
   ```

2. **Install dependencies**:
   ```bash
   uv sync
   ```

3. **Install to Claude Desktop**:

    Install the server as a Claude Desktop application:
    ```bash
    uv run mcp install main.py --name "Ethereum Validator Queue"
    ```

    Configuration file as a reference:

    ```json
    {
       "mcpServers": {
           "Ethereum Validator Queue": {
               "command": "uv",
               "args": [ "--directory", "/path/to/ethereum-validator-queue-mcp", "run", "main.py" ]
           }
       }
    }
    ```
    Replace `/path/to/ethereum-validator-queue-mcp` with your actual installation path.
    
## Usage 

### Tools and Prompts

- **Tools**:
  - `get_activation_queue()`: Returns activation queue stats, e.g., "Current activation queue length: 7189 validators, Total active validators: 1084363, Entering validators balance: 283043.84 ETH, Estimated wait time: Approximately 8.0 days."
  - `get_exit_queue()`: Returns exit queue stats, e.g., "Current exit queue length: 27152 validators, Total active validators: 1084363, Exiting validators balance: 882528.00 ETH, Estimated wait time: Approximately 30.2 days."
  - `get_validator_status(pubkey)`: Returns validator details for a given public key (48-byte hex string starting with '0x'), e.g., "Validator 0x1234...: Status: active_online, Effective Balance: 32.00 ETH, Activation Epoch: 123456, Exit Epoch: N/A."

- **Prompt**:
  - `analyze_queue()`: Generates a prompt for LLMs to analyze queue trends, e.g., "Analyze the current Ethereum validator queues: What do the current queue lengths indicate about staking demand? How might this impact ETH price and network security? Provide historical context if possible."

### Example Interaction

Below are examples of natural language prompts you might use in an MCP-compatible client (e.g., Claude Desktop) and the corresponding outputs from the server, based on sample data.

1. **Get Activation Queue Statistics**:
   - **Prompt**: "Show me the current Ethereum validator activation queue status."
   - **Command**: `get_activation_queue()`
   - **Output**:
     ```
     Current activation queue length: 7189 validators
     Total active validators: 1084363
     Entering validators balance: 283043.84 ETH
     Estimated wait time: Approximately 8.0 days (assuming ~900 activations per day)
     ```

2. **Get Exit Queue Statistics**:
   - **Prompt**: "What's the status of the Ethereum validator exit queue?"
   - **Command**: `get_exit_queue()`
   - **Output**:
     ```
     Current exit queue length: 27152 validators
     Total active validators: 1084363
     Exiting validators balance: 882528.00 ETH
     Estimated wait time: Approximately 30.2 days (assuming ~900 exits per day)
     ```

3. **Get Validator Status**:
   - **Prompt**: "Check the status of the validator with public key 0x93247f2f..."
   - **Command**: `get_validator_status("0x93247f2f...")`
   - **Output** (assuming sample data from the API):
     ```
     Validator 0x93247f2f...:
     Status: active_online
     Effective Balance: 32.00 ETH
     Activation Epoch: 123456
     Exit Epoch: N/A
     ```

4. **Analyze Queue Trends**:
   - **Prompt**: "Analyze the current Ethereum validator queue trends."
   - **Command**: `analyze_queue()`
   - **Output** (prompt sent to LLM for analysis):
     ```
     Analyze the current Ethereum validator queues:
     - What do the current queue lengths indicate about staking demand?
     - How might this impact ETH price and network security?
     - Provide historical context if possible.
     ```
     - **LLM Response** (example, depends on the LLM):
       ```
       The current Ethereum validator queues show a significant exit queue (27,152 validators) compared to the activation queue (7,189 validators), indicating a higher number of validators are leaving than joining. This could suggest reduced staking demand, possibly due to market conditions or profitability concerns. The large exiting balance (882,528 ETH) may increase selling pressure on ETH, potentially impacting its price negatively in the short term. However, the network remains secure with over 1 million active validators. Historically, exit queue spikes have occurred during market downturns or after major network upgrades (e.g., Shanghai upgrade). Further analysis of staking rewards and market trends is recommended.
       ```


## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.