Whale Tracker MCP Server

1# Whale Tracker MCP Server
2 
3 
4**A Model Context Protocol (MCP) server for tracking cryptocurrency whale transactions using the Whale Alert API**
5 
6[![mit license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit/)
7[![python versions](https://img.shields.io/pypi/pyversions/mcp)](https://www.python.org/downloads/)
8[![smithery badge](https://smithery.ai/badge/@kukapay/whale-tracker-mcp)](https://smithery.ai/server/@kukapay/whale-tracker-mcp)
9 
10<!-- omit in toc -->
11## Table of Contents
12 
13- [Overview](#overview)
14- [Features](#features)
15- [Prerequisites](#prerequisites)
16- [Installation](#installation)
17- [Usage](#usage)
18  - [Running in Development Mode](#running-in-development-mode)
19  - [Integrating with Claude Desktop](#integrating-with-claude-desktop)
20  - [Direct Execution](#direct-execution)
21- [Examples](#examples)
22- [API Key Configuration](#api-key-configuration)
23- [License](#license)
24- [Acknowledgements](#acknowledgements)
25 
26 
27## Overview
28 
29The `whale-tracker-mcp` server is a Python-based implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) that integrates with the [Whale Alert API](https://docs.whale-alert.io/#endpoints). It enables real-time tracking and analysis of large cryptocurrency transactions ("whale" movements) by exposing tools, resources, and prompts to MCP-compatible clients like Claude Desktop.
30 
31This server is designed for cryptocurrency enthusiasts, developers, and analysts who want to monitor whale activity directly within their LLM-powered workflows.
32 
33## Features
34 
35- **Tools**:
36  - `get_recent_transactions`: Fetch recent whale transactions with optional filters for blockchain, minimum value, and limit.
37  - `get_transaction_details`: Retrieve detailed information about a specific transaction by its ID.
38- **Resources**:
39  - `whale://transactions/{blockchain}`: Expose recent transactions for a specified blockchain as contextual data.
40- **Prompts**:
41  - `query_whale_activity`: A reusable template for analyzing whale transaction patterns, optionally filtered by blockchain.
42- **Asynchronous API Calls**: Uses `httpx` for efficient, non-blocking requests to the Whale Alert API.
43- **Environment Variable Support**: Securely manage your API key via a `.env` file.
44 
45## Prerequisites
46 
47- **Python**: Version 3.10 or higher.
48- **Whale Alert API Key**: Sign up at [whale-alert.io](https://whale-alert.io/) to obtain an API key.
49- **MCP Client**: Compatible with MCP clients like Claude Desktop or the MCP Inspector.
50 
51## Installation
52 
53### Installing via Smithery
54 
55To install Whale Tracker for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kukapay/whale-tracker-mcp):
56 
57```bash
58npx -y @smithery/cli install @kukapay/whale-tracker-mcp --client claude
59```
60 
611. **Clone the repository**:
62```bash
63git clone https://github.com/kukapay/whale-tracker-mcp.git
64cd whale-tracker-mcp
65```
662. Install dependencies: We recommend using uv for dependency management:
67```bash
68uv add "mcp[cli]" httpx python-dotenv
69```   
70Alternatively, use pip:
71```bash
72pip install mcp httpx python-dotenv
73```
743. Set up your API key: Create a .env file in the project root and add your Whale Alert API key:
75```
76WHALE_ALERT_API_KEY=your_api_key_here
77```
78 
79## Usage
80### Running in Development Mode
81 
82Test the server locally with the MCP Inspector:
83 
84```bash
85mcp dev whale_tracker.py --with-editable .
86```
87 
88This opens a web interface where you can explore the server's tools, resources, and prompts.
89 
90### Integrating with Claude Desktop
91 
92Install the server into Claude Desktop for seamless integration:
93 
94```bash
95mcp install whale_tracker.py --name "WhaleTracker" -f .env
96```
97 
98- `--name "WhaleTracker"`: Sets a custom name for the server in Claude Desktop.
99- `-f .env`: Loads the API key from the .env file.
100 
101Restart Claude Desktop after installation. Look for the hammer icon in the input box to confirm the server is loaded, then try commands like:
102 
103- "Show me recent whale transactions on Bitcoin."
104- "Get details for transaction ID 123456789."
105- "Analyze whale activity on Ethereum."
106 
107### Direct Execution
108 
109Run the server standalone for custom deployments:
110 
111```bash
112python whale_tracker.py
113```
114 
115Or use the MCP CLI:
116 
117```bash
118mcp run whale_tracker.py
119```
120 
121## Examples
122 
123Here’s how you might interact with the server in Claude Desktop:
124 
125### Fetch Recent Transactions:
126 
127```text
128What are the latest whale transactions on Ethereum with a minimum value of $1,000,000?
129```
130The server calls `get_recent_transactions` with `blockchain="ethereum"` and `min_value=1000000`.
131 
132### Get Transaction Details:
133 
134```text
135Tell me about transaction ID 123456789.
136```
137 
138The server uses `get_transaction_details` to fetch and display the transaction data.
139 
140### Analyze Whale Activity:
141 
142```text
143Analyze recent whale transactions on Bitcoin.
144```
145 
146The `query_whale_activity` prompt triggers an analysis based on the `whale://transactions/bitcoin` resource.
147 
148## API Key Configuration
149 
150The server requires a Whale Alert API key, which is loaded from the `WHALE_ALERT_API_KEY` environment variable. To configure it:
151 
152- Create a .env file:
153```text
154WHALE_ALERT_API_KEY=your_api_key_here
155```
156- Ensure `python-dotenv` is installed (included in the dependencies).
157- The server will automatically load the key at startup.
158 
159Alternatively, pass the key directly when running the server:
160 
161```bash
162mcp install whale_tracker.py -v WHALE_ALERT_API_KEY=your_api_key_here
163```
164 
165## License
166 
167This project is licensed under the MIT License. See the LICENSE file for details.
168 
169## Acknowledgements
170 
171- Whale Alert for providing the API to track cryptocurrency whale transactions.
172- Model Context Protocol team for the MCP specification and Python SDK.
173- httpx for a robust HTTP client library.
174 
175Happy whale tracking! 🐳
176