Blockchain wallet analytics MCP

MCP server for retriving on-chain wallet swap transactions. Fetches and parses swap data from blockchain wallets for LLM based analysis.

Features

• DEX detection — Identifies Raydium, Jupiter, Meteora, Orca, Pump.fun from transaction instructions
• Token classification — Auto-labels stablecoins, base currencies, and meme tokens
• Transaction categories — Classifies swaps, transfers, staking, NFT mints
• Multi-hop support — Aggregates complex swap paths into single entries
• Currency-agnostic filters — min_amount_sent/received work on any token, not just SOL
• RPC auto-detection — Single SOLANA_RPC_URL config; detects provider from URL

Supported Chains

Chain	Status	Env Var
Solana	✅ Implemented	SOLANA_RPC_URL
Ethereum	🔜 Planned	ETH_RPC_URL
Base	🔜 Planned	BASE_RPC_URL
BSC	🔜 Planned	BSC_RPC_URL

The parser is chain-agnostic in design — swap detection logic applies to any EVM or Solana wallet. New chains are added by extending the transaction parsing module.

Use Cases

Use Case	Description	Recommended Filters
Copy Trading	Track a profitable wallet's swaps in real-time and mirror their trades	token_type_filter="meme" to focus on high-risk, high-reward plays
Wallet Profiling	Analyze trading patterns — preferred DEX, position sizes, token preferences	No filters; use full data for strategy and risk assessment
Alpha Discovery	Scan wallets connected to new token launches	exclude_categories=["transfer", "staking"] to isolate pure swap activity
DeFi Analytics	Aggregate swap volume across a portfolio of wallets	min_amount_sent to filter out dust trades
Stablecoin Flow Tracking	Monitor large stablecoin movements for capital inflows/outflows	token_type_filter="stablecoin", min_amount_sent=10000

Installation

pip install wallet-analytics-mcp

Or via uv:

uv pip install wallet-analytics-mcp

Quick Start

Run without installing using uvx:

uvx wallet-analytics-mcp

Configuring an MCP Client

Add to your client's MCP configuration. Example for Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wallet-analytics": {
      "command": "uvx",
      "args": ["wallet-analytics-mcp"],
      "env": {
        "SOLANA_RPC_URL": "https://your-rpc-endpoint"
      }
    }
  }
}

The env block passes variables directly to the server subprocess — no need to export them globally. Other MCP-compatible clients (Cursor, Windsurf, Cline, etc.) use the same JSON config format.

Configuration

All settings via environment variables:

Variable	Default	Description
SOLANA_RPC_URL	Solana public RPC	Any Solana RPC endpoint (Alchemy, Helius, QuickNode)
SOLANA_RPC_TIMEOUT	30	RPC timeout in seconds
SOLANA_TX_LIMIT	30000	Max transactions per wallet

Point SOLANA_RPC_URL at any provider — Alchemy, Helius, QuickNode, etc. Falls back to Solana public if not set.

Available Tools

get_raw_transactions

Fetch all detected swap transactions for a wallet address. By default returns every swap regardless of token pair. Optional filters let the LLM narrow results.

Parameters:

Parameter	Type	Required	Description
wallet_address	string	Yes	Solana wallet public key (base58)
start_date	string	No	ISO 8601 date (default: 30 days ago)
end_date	string	No	ISO 8601 date (default: now)
filter_stablecoin_pairs	bool	No	Drop swaps where both tokens are base currencies (default: false)
token_type_filter	string	No	"meme" — keep swaps with at least one non-stablecoin token; "stablecoin" — keep only stablecoin/base swaps
min_amount_sent	number	No	Minimum token quantity sent to include the swap
min_amount_received	number	No	Minimum token quantity received to include the swap
exclude_categories	list	No	Categories to exclude: "transfer", "staking", "nft", "other"

Returns: List of swaps with token pairs, quantities, timestamps, signatures, DEX platform, and transaction category. Response includes filters_applied showing which filters were active.

Design

The parser returns all detected swaps — no hard-coded drops. Filtering happens at the tool level so the LLM decides what's relevant. Each swap includes:

• Platform — Detected DEX program (Raydium, Jupiter, Meteora, Orca, Pump.fun) from transaction instructions
• Category — Transaction type (swap, transfer, staking, nft, other) based on program IDs called
• Token Symbols — Human-readable symbols for known tokens (e.g., BONK, WIF, POPCAT)

This catches USDC→meme swaps, meme-to-meme trades, and any other token pair.

Logging

Logs written to log/mcp_server.log in the package directory.

Attribution

This project was generated by Qwen3.6-27B (Q3_K_M quant) running locally via llama.cpp. Key inference settings:

• Context: 65,536 tokens
• Temperature: 0.6, Top-K: 20, Top-P: 0.95
• Presence penalty: 1.5
• Flash attention enabled, Q8_0 KV cache

License

MIT