# Blockchain wallet analytics MCP

[![PyPI](https://img.shields.io/pypi/v/wallet-analytics-mcp)](https://pypi.org/project/wallet-analytics-mcp/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Coverage](https://img.shields.io/badge/coverage-82%25-yellowgreen)](tests/)
[![Last Commit](https://img.shields.io/github/last-commit/santhoshraje/wallet-analytics-mcp)](https://github.com/santhoshraje/wallet-analytics-mcp/commits/main)

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

```bash
pip install wallet-analytics-mcp
```

Or via [uv](https://github.com/astral-sh/uv):

```bash
uv pip install wallet-analytics-mcp
```

## Quick Start

Run without installing using `uvx`:

```bash
uvx wallet-analytics-mcp
```

### Configuring an MCP Client

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

```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.

## 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