Hyperliquid WhaleAlert MCP

1# Hyperliquid WhaleAlert MCP
2 
3An MCP server that provides real-time whale alerts on Hyperliquid, flagging positions with a notional value exceeding $1 million.
4 
5![GitHub License](https://img.shields.io/github/license/kukapay/hyperliquid-whalealert-mcp)
6![Python Version](https://img.shields.io/badge/python-3.10+-blue)
7![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
8 
9<a href="https://glama.ai/mcp/servers/@kukapay/hyperliquid-whalealert-mcp">
10  <img width="380" height="200" src="https://glama.ai/mcp/servers/@kukapay/hyperliquid-whalealert-mcp/badge" alt="hyperliquid-whalealert-mcp MCP server" />
11</a>
12 
13## Features
14 
15- **Tool: `get_whale_alerts`**: Fetches recent whale transactions and returns them as a Markdown table using `pandas` for clean formatting.
16- **Prompt: `summarize_whale_activity`**: Generates a summary of whale transactions, including metrics like total position value and notable symbols.
17 
18## Prerequisites
19 
20- **Python**: Version 3.10 or higher.
21- **CoinGlass API Key**: Obtain from [CoinGlass](https://www.coinglass.com/) (required for API access).
22- **uv**: Package and dependency manager ([install uv](https://docs.astral.sh/uv/)).
23 
24## Installation
25 
261. **Clone the Repository**:
27   ```bash
28   git clone https://github.com/kukapay/hyperliquid-whalealert-mcp.git
29   cd hyperliquid-whalealert-mcp
30   ```
31 
322. **Install Dependencies**:
33   ```bash
34   uv sync
35   ```
36   This installs dependencies specified in `pyproject.toml`.
37 
383. **Claude Desktop Integration**:
39   Install the server in Claude Desktop:
40   ```bash
41   uv run mcp install mcp.py --name "Hyperliquid Whale Alert"
42   ```
43   
44    Or update the configuration file manually:
45  
46    ```
47    {
48      "mcpServers": {
49        "hyperliquid-whalealert": {
50          "command": "uv",
51          "args": [ "--directory", "/path/to/hyperliquid-whalealert-mcp", "run", "main.py" ],
52          "env": { "COINGLASS_API_KEY": "your_api_key" }
53        }
54      }
55    }
56    ```       
57    Replace `/path/to/hyperliquid-whalealert-mcp` with your actual installation path and `COINGLASS_API_KEY` with your API key.
58 
59## Usage
60 
61### Using the Tool
62 
63The `get_whale_alerts` tool fetches whale transaction data and returns it as a Markdown list. Example output:
64 
65```markdown
66- **ETH Transaction**:
67  - User Address: 0x3fd4444154242720c0d0c61c74a240d90c127d33
68  - Position Size: 12700
69  - Entry Price: $1611.62
70  - Liquidation Price: $527.2521
71  - Position Value (USD): $21003260
72  - Action: Close
73  - Create Time: 2025-05-20 12:31:57
74- **BTC Transaction**:
75  - User Address: 0x1cadadf0e884ac5527ae596a4fc1017a4ffd4e2c
76  - Position Size: 33.54032
77  - Entry Price: $87486.2
78  - Liquidation Price: $44836.8126
79  - Position Value (USD): $2936421.4757
80  - Action: Close
81  - Create Time: 2025-05-20 12:31:17
82```
83  
84To invoke the tool:
85- In the MCP Inspector, select `get_whale_alerts` and execute.
86- In Claude Desktop, use the registered server and call the tool via the UI or API.
87 
88### Using the Prompt
89 
90The `summarize_whale_activity` prompt generates a summary of whale transactions. Example interaction (in a compatible client):
91 
92```plaintext
93/summarize_whale_activity
94```
95 
96Response:
97```
98I'll analyze the whale transaction data and provide a summary.
99```
100 
101This can be extended by LLMs to provide detailed metrics like total position value or notable symbols.
102 
103 
104## License
105 
106This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.