Whale Tracker MCP Server for Cryptocurrency Transactions

Overview

The Whale Tracker MCP server monitors large cryptocurrency transfers (“whale” transactions) and exposes those events in real time for downstream systems. It bridges on-chain event streams with webhooks, WebSocket subscriptions, and Model Context Protocol (MCP) tooling so that apps, bots, or LLMs can fetch or subscribe to high-value token or native-asset movements across configurable blockchains.

This server is useful for trading desks, compliance teams, market-research engineers, and developer integrations that need near-instant visibility into large transfers (for example, exchange inflows/outflows or transfers between cold wallets). It provides configurable thresholds, multi-network support, and lightweight endpoints to integrate whale events into alerting systems or automated workflows.

Features

• Real-time detection of large token and native-asset transfers across configurable networks
• Configurable whale threshold (amount or USD-equivalent)
• Webhook delivery for automated alerts and integrations
• WebSocket feed for low-latency event streaming
• Simple REST endpoints for status, subscriptions, and historical queries
• Docker and local development support with environment-based configuration
• Extensible pipeline to add custom filters, enrichment (price, token metadata), and persistence
• Designed to be used as an MCP server so LLMs and tools can request recent whale activity

Installation / Configuration

Prerequisites:

• Docker (recommended) or Node.js >= 16 / Python 3.8+ depending on the implementation
• RPC / WebSocket provider (e.g., Alchemy, Infura or other archive node)
• Optional: API key for price feeds (CoinGecko, CoinMarketCap) to convert amounts to USD

Clone the repository and start locally:

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

Local Node.js example:

# Install and run (Node.js example)
npm install
cp .env.example .env   # edit configuration values in .env
npm run start

Docker example:

# Build and run with Docker
docker build -t whale-tracker-mcp .
docker run -e RPC_URL="<your_rpc_url>" -e THRESHOLD_USD=100000 \
  -p 8080:8080 whale-tracker-mcp

docker-compose example:

version: "3.8"
services:
  whale-tracker:
    image: whale-tracker-mcp:latest
    build: .
    ports:
      - 8080:8080
    environment:
      RPC_URL: "${RPC_URL}"
      THRESHOLD_USD: "${THRESHOLD_USD:-100000}"
      PORT: "${PORT:-8080}"
      WEBHOOK_SECRET: "${WEBHOOK_SECRET}"

Example .env (edit to match your provider and preferences):

PORT=8080
RPC_URL=wss://eth-mainnet.alchemyapi.io/v2/YOUR_KEY
NETWORKS=ethereum,polygon
THRESHOLD_USD=100000
PRICE_FEED_API_KEY=your_price_api_key
WEBHOOK_SECRET=supersecret

Common environment variables:

Available Tools / Resources

The server provides a small set of REST and realtime primitives useful for integrations and MCP tool calls.

Endpoints (examples):

• GET /status
  • Returns server health and active network subscriptions.
• GET /events?limit=10
  • Returns recent whale events (JSON list).
• POST /webhooks/subscribe
  • Subscribe a webhook URL to receive future whale events.
  • Payload: { “url”: “https://example.com/hook”, “networks”: [“ethereum”], “min_usd”: 250000 }
• POST /simulate
  • Trigger a simulated event for testing (useful for webhook validation).

WebSocket:

• ws://:/stream
  • Subscribes to live whale events; message payload is the same JSON event delivered to webhooks.

  Sample webhook event payload:

  {
    "id": "evt_01F...",
    "network": "ethereum",
    "tx_hash": "0xabc123...",
    "timestamp": 1680000000,
    "from": "0xFromAddress",
    "to": "0xToAddress",
    "asset": "ETH",
    "amount": "1200.5",
    "amount_usd": 2100000,
    "token_address": null,
    "confirmed": true
  }
  

  Security:

  • Webhooks can be signed using HMAC and the configured WEBHOOK_SECRET.
  • Use IP allowlists or authentication middleware for management endpoints.

  Use Cases

  • Exchange inflow/outflow monitoring: Trigger alerts when large amounts are moved into or out of known exchange addresses, aiding operations and liquidity teams.
  • Early-warning trading signals: Feed large-transfer data into algo strategies or dashboards to detect potential price-moving events.
  • Compliance and audit: Monitor movements from or to high-risk addresses, enabling automated case creation in compliance tooling.
  • Portfolio monitoring: Notify large holders or DAO treasuries when substantial transfers occur to or from multisigs or treasury wallets.
  • LLM tooling via MCP: An LLM acting as an assistant can call the server to fetch recent whale events when answering market-moving questions or drafting alerts.

  Notes and Best Practices

  • Tune THRESHOLD_USD per network and token volatility; consider using rolling average prices for conversion.
  • Use dedicated RPC/WebSocket providers or rate-limited endpoints for production-grade monitoring.
  • Persist events or use an event queue (Kafka/Redis) if you need reliable delivery and replayability.
  • Protect management APIs and webhook subscription endpoints behind authentication or ACLs.

  Resources:

  • GitHub repository: https://github.com/kukapay/whale-tracker-mcp
  • Consider integrating price feeds (CoinGecko) and address-labeling services for richer event context.
  Tags:finance