Whale Tracker

by kukapay

9 stars

271 downloads

Not rated

GitHub

About

Monitors real-time cryptocurrency whale transactions across blockchains, providing detailed transaction information and configurable filtering for traders and analysts tracking significant market movements.

Details

Author: kukapay
Repository: kukapay/whale-tracker-mcp
GitHub stars: 9
Downloads: 271
License: MIT License
Categories: AI, Design, Developer Tools, Search, API, Knowledge Base, Infrastructure, Other

- Tools:
- get_recent_transactions: Fetch recent whale transactions with optional filters for blockchain, minimum value, and limit.
- get_transaction_details: Retrieve detailed information about a specific transaction by its ID.
- Resources:
- whale://transactions/{blockchain}: Expose recent transactions for a specified blockchain as contextual data.
- Prompts:
- query_whale_activity: A reusable template for analyzing whale transaction patterns, optionally filtered by blockchain.
- Asynchronous API Calls: Uses httpx for efficient, non-blocking requests to the Whale Alert API.
- Environment Variable Support: Securely manage your API key via a .env file.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Whale Tracker

Command (node, npx, python, etc.) python
Arguments
- Argument 1 whale_tracker.py
Environment
- WHALE_ALERT_API_KEY your_api_key_here
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

JSON

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

From the repository

To install Whale Tracker for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @kukapay/whale-tracker-mcp --client claude

1. Clone the repository:

git clone https://github.com/kukapay/whale-tracker-mcp.git

cd whale-tracker-mcp

2. Install dependencies: We recommend using uv for dependency management:

uv add "mcp[cli]" httpx python-dotenv

Alternatively, use pip:

pip install mcp httpx python-dotenv

3. Set up your API key: Create a .env file in the project root and add your Whale Alert API key:

WHALE_ALERT_API_KEY=your_api_key_here

Test the server locally with the MCP Inspector:

mcp dev whale_tracker.py --with-editable .

This opens a web interface where you can explore the server's tools, resources, and prompts.

The server requires a Whale Alert API key, which is loaded from the WHALE_ALERT_API_KEY environment variable. To configure it:

- Create a .env file:

WHALE_ALERT_API_KEY=your_api_key_here

- Ensure python-dotenv is installed (included in the dependencies).
- The server will automatically load the key at startup.

Alternatively, pass the key directly when running the server:

mcp install whale_tracker.py -v WHALE_ALERT_API_KEY=your_api_key_here

`get_recent_transactions`

Fetch recent whale transactions with optional filters for blockchain, minimum value, and limit.

`get_transaction_details`

Retrieve detailed information about a specific transaction by its ID.

`query_whale_activity`

A reusable template for analyzing whale transaction patterns, optionally filtered by blockchain.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "whale tracker": {
            "env": {
                "WHALE_ALERT_API_KEY": "your_api_key_here"
            },
            "args": [
                "whale_tracker.py"
            ],
            "command": "python"
        }
    }
}

Linux

{
    "env": {
        "WHALE_ALERT_API_KEY": "your_api_key_here"
    },
    "args": [
        "whale_tracker.py"
    ],
    "command": "python"
}

Macos

{
    "env": {
        "WHALE_ALERT_API_KEY": "your_api_key_here"
    },
    "args": [
        "whale_tracker.py"
    ],
    "command": "python"
}

Windows

{
    "env": {
        "WHALE_ALERT_API_KEY": "your_api_key_here"
    },
    "args": [
        "whale_tracker.py"
    ],
    "command": "python"
}

Whale Tracker MCP Server

A Model Context Protocol (MCP) server for tracking cryptocurrency whale transactions using the Whale Alert API

- Overview
- Features
- Prerequisites
- Installation
- Usage
- Running in Development Mode
- Integrating with Claude Desktop
- Direct Execution
- Examples
- API Key Configuration
- License
- Acknowledgements

Overview

The whale-tracker-mcp server is a Python-based implementation of the Model Context Protocol (MCP) that integrates with the Whale Alert API. 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.

This server is designed for cryptocurrency enthusiasts, developers, and analysts who want to monitor whale activity directly within their LLM-powered workflows.

Features

Prerequisites

- Python: Version 3.10 or higher.
- Whale Alert API Key: Sign up at whale-alert.io to obtain an API key.
- MCP Client: Compatible with MCP clients like Claude Desktop or the MCP Inspector.

Installation

Installing via Smithery

To install Whale Tracker for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @kukapay/whale-tracker-mcp --client claude

1. Clone the repository:

git clone https://github.com/kukapay/whale-tracker-mcp.git

cd whale-tracker-mcp

2. Install dependencies: We recommend using uv for dependency management:

uv add "mcp[cli]" httpx python-dotenv

Alternatively, use pip:

pip install mcp httpx python-dotenv

3. Set up your API key: Create a .env file in the project root and add your Whale Alert API key:

WHALE_ALERT_API_KEY=your_api_key_here

Usage

Running in Development Mode

Test the server locally with the MCP Inspector:

mcp dev whale_tracker.py --with-editable .

This opens a web interface where you can explore the server's tools, resources, and prompts.

Integrating with Claude Desktop

Install the server into Claude Desktop for seamless integration:

mcp install whale_tracker.py --name "WhaleTracker" -f .env

- --name "WhaleTracker": Sets a custom name for the server in Claude Desktop.
- -f .env: Loads the API key from the .env file.

Restart Claude Desktop after installation. Look for the hammer icon in the input box to confirm the server is loaded, then try commands like:

- "Show me recent whale transactions on Bitcoin."
- "Get details for transaction ID 123456789."
- "Analyze whale activity on Ethereum."

Direct Execution

Run the server standalone for custom deployments:

python whale_tracker.py

Or use the MCP CLI:

mcp run whale_tracker.py

Examples

Here’s how you might interact with the server in Claude Desktop:

Fetch Recent Transactions:

What are the latest whale transactions on Ethereum with a minimum value of $1,000,000?

The server calls get_recent_transactions with blockchain="ethereum" and min_value=1000000.

Get Transaction Details:

Tell me about transaction ID 123456789.

The server uses get_transaction_details to fetch and display the transaction data.

Analyze Whale Activity:

Analyze recent whale transactions on Bitcoin.

The query_whale_activity prompt triggers an analysis based on the whale://transactions/bitcoin resource.

API Key Configuration

The server requires a Whale Alert API key, which is loaded from the WHALE_ALERT_API_KEY environment variable. To configure it:

- Create a .env file:

WHALE_ALERT_API_KEY=your_api_key_here

- Ensure python-dotenv is installed (included in the dependencies).
- The server will automatically load the key at startup.

Alternatively, pass the key directly when running the server:

mcp install whale_tracker.py -v WHALE_ALERT_API_KEY=your_api_key_here

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

- Whale Alert for providing the API to track cryptocurrency whale transactions.
- Model Context Protocol team for the MCP specification and Python SDK.
- httpx for a robust HTTP client library.

Happy whale tracking! 🐳

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_recent_transactions

get_transaction_details

query_whale_activity

Claude Desktop / Cursor

Linux

Macos

Windows

Whale Tracker MCP Server

Table of Contents

Overview

Features

Prerequisites

Installation

Installing via Smithery

Usage

Running in Development Mode

Integrating with Claude Desktop

Direct Execution

Examples

Fetch Recent Transactions:

Get Transaction Details:

Analyze Whale Activity:

API Key Configuration

License

Acknowledgements

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`get_recent_transactions`

`get_transaction_details`

`query_whale_activity`