# helius-forensics-mcp

Solana wallet forensics via MCP. Trace funds, identify entities, score risk — powered by [Helius](https://helius.dev) APIs.

Turn any MCP-compatible AI client into a Solana blockchain investigator.

## Quick Start

```bash
npx helius-forensics-mcp
```

### Claude Desktop Config

```json
{
  "mcpServers": {
    "helius-forensics": {
      "command": "npx",
      "args": ["helius-forensics-mcp"],
      "env": {
        "HELIUS_API_KEY": "your-key-here"
      }
    }
  }
}
```

Get a free API key at [dashboard.helius.dev](https://dashboard.helius.dev).

## Tools

### `investigate_wallet`

Full forensics report for any Solana wallet — identity, funding source, balances, activity summary, and risk score.

> "Investigate wallet `7xKp...3nQm`"

### `trace_funding`

Follow the money upstream. Recursively traces funding sources to find where the SOL originally came from.

```
7xKp...3nQm
  ← 9aB2...mR4x (Unknown) — 2.5 SOL @ 2024-03-15
    ← 3kF7...9pLq (Binance Hot Wallet) [exchange]
```

### `trace_outflows`

Follow the money downstream. Maps top destinations by volume with identity labels.

### `identify_wallets`

Batch lookup for up to 100 addresses. Tags exchanges, protocols, institutions from Helius's database of 7,000+ known accounts.

### `wallet_risk_score`

Composite risk score (0-100) based on:
- Funding source (exchange vs mixer vs unknown)
- Wallet age
- Transfer patterns (rapid in/out detection)
- Counterparty analysis

### `compare_wallets`

Compare 2-5 wallets to find connections:
- Shared counterparties
- Overlapping token holdings
- Timing correlation
- Same-owner probability

## How It Works

This MCP server composes Helius's Wallet API and Enhanced Transactions API into forensics workflows. Instead of calling raw API methods, the AI calls high-level tools like `investigate_wallet` and gets a complete picture.

**APIs used:**
- [Wallet Identity](https://www.helius.dev/docs/wallet-api/overview) — 7,000+ tagged accounts
- [Funded By](https://www.helius.dev/docs/wallet-api/overview) — original funding source discovery
- [Wallet Balances](https://www.helius.dev/docs/wallet-api/overview) — token + NFT holdings with USD values
- [Wallet Transfers](https://www.helius.dev/docs/wallet-api/overview) — complete transfer history
- [Enhanced Transactions](https://www.helius.dev/docs/enhanced-transactions) — human-readable transaction parsing

## Requirements

- Node.js 18+
- Free Helius API key ([get one here](https://dashboard.helius.dev))

## Development

```bash
git clone https://github.com/drtiibiird/helius-forensics-mcp.git
cd helius-forensics-mcp
npm install
npm run build
```

Test locally:

```bash
HELIUS_API_KEY=your-key node dist/index.js
```

## License

MIT