Ethereum Validator Queue MCP

1# Ethereum Validator Queue MCP
2 
3An 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.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/ethereum-validator-queue-mcp) 
6![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9## Features
10 
11- **Tools**:
12  - `get_activation_queue`: Retrieves statistics about the Ethereum validator activation queue, including queue length, total active validators, entering validators' balance, and estimated wait time.
13  - `get_exit_queue`: Retrieves statistics about the Ethereum validator exit queue, including queue length, total active validators, exiting validators' balance, and estimated wait time.
14  - `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.
15- **Prompt**:
16  - `analyze_queue`: A reusable prompt template for LLMs to analyze validator queue trends, including staking demand, impact on ETH price, and network security.
17 
18## Installation
19 
20### Prerequisites
21 
22- **Python**: Version 3.10 or higher
23- **uv**: A fast and modern Python package manager ([installation instructions](https://docs.astral.sh/uv/))
24 
25### Setup
26 
271. **Clone the Repository**:
28   ```bash
29   git clone https://github.com/kukapay/ethereum-validator-queue-mcp.git
30   cd ethereum-validator-queue-mcp
31   ```
32 
332. **Install dependencies**:
34   ```bash
35   uv sync
36   ```
37 
383. **Install to Claude Desktop**:
39 
40    Install the server as a Claude Desktop application:
41    ```bash
42    uv run mcp install main.py --name "Ethereum Validator Queue"
43    ```
44 
45    Configuration file as a reference:
46 
47    ```json
48    {
49       "mcpServers": {
50           "Ethereum Validator Queue": {
51               "command": "uv",
52               "args": [ "--directory", "/path/to/ethereum-validator-queue-mcp", "run", "main.py" ]
53           }
54       }
55    }
56    ```
57    Replace `/path/to/ethereum-validator-queue-mcp` with your actual installation path.
58    
59## Usage 
60 
61### Tools and Prompts
62 
63- **Tools**:
64  - `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."
65  - `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."
66  - `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."
67 
68- **Prompt**:
69  - `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."
70 
71### Example Interaction
72 
73Below 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.
74 
751. **Get Activation Queue Statistics**:
76   - **Prompt**: "Show me the current Ethereum validator activation queue status."
77   - **Command**: `get_activation_queue()`
78   - **Output**:
79     ```
80     Current activation queue length: 7189 validators
81     Total active validators: 1084363
82     Entering validators balance: 283043.84 ETH
83     Estimated wait time: Approximately 8.0 days (assuming ~900 activations per day)
84     ```
85 
862. **Get Exit Queue Statistics**:
87   - **Prompt**: "What's the status of the Ethereum validator exit queue?"
88   - **Command**: `get_exit_queue()`
89   - **Output**:
90     ```
91     Current exit queue length: 27152 validators
92     Total active validators: 1084363
93     Exiting validators balance: 882528.00 ETH
94     Estimated wait time: Approximately 30.2 days (assuming ~900 exits per day)
95     ```
96 
973. **Get Validator Status**:
98   - **Prompt**: "Check the status of the validator with public key 0x93247f2f..."
99   - **Command**: `get_validator_status("0x93247f2f...")`
100   - **Output** (assuming sample data from the API):
101     ```
102     Validator 0x93247f2f...:
103     Status: active_online
104     Effective Balance: 32.00 ETH
105     Activation Epoch: 123456
106     Exit Epoch: N/A
107     ```
108 
1094. **Analyze Queue Trends**:
110   - **Prompt**: "Analyze the current Ethereum validator queue trends."
111   - **Command**: `analyze_queue()`
112   - **Output** (prompt sent to LLM for analysis):
113     ```
114     Analyze the current Ethereum validator queues:
115     - What do the current queue lengths indicate about staking demand?
116     - How might this impact ETH price and network security?
117     - Provide historical context if possible.
118     ```
119     - **LLM Response** (example, depends on the LLM):
120       ```
121       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.
122       ```
123 
124 
125## License
126 
127This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
128 
129