# Solana Forensics MCP

On-chain investigation and analysis tools for Solana blockchain. Detects wash trading, traces funding sources, analyzes holder concentration, and identifies MEV/bundle activity.

## Quick Start

### 1. Get a Helius API Key

Sign up at [dashboard.helius.dev](https://dashboard.helius.dev) and create an API key.

### 2. Install

```bash
cd solana-forensics-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
```

### 3. Configure Your Client

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "solana-forensics": {
      "command": "uv",
      "args": ["--directory", "/path/to/solana-forensics-mcp", "run", "python", "-m", "src.server"],
      "env": {
        "HELIUS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. The server will appear as `solana-forensics` with 4 tools.

</details>

<details>
<summary><strong>Claude Code (CLI)</strong></summary>

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "solana-forensics": {
      "command": "uv",
      "args": ["--directory", "/path/to/solana-forensics-mcp", "run", "python", "-m", "src.server"],
      "env": {
        "HELIUS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or add to your project's `.mcp.json` for project-specific access:

```json
{
  "mcpServers": {
    "solana-forensics": {
      "command": "uv",
      "args": ["--directory", "/path/to/solana-forensics-mcp", "run", "python", "-m", "src.server"],
      "env": {
        "HELIUS_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Code. Tools will be available as `mcp__solana-forensics__*`.

</details>

## Forensics Operations

| Operation | Description |
|-----------|-------------|
| `forensics.trace_sol_funding` | BFS traversal of SOL transfer history to trace funding sources |
| `forensics.find_common_funding` | Identify shared funding sources across multiple wallets |
| `forensics.detect_wash_trading` | DFS cycle detection in token trade graphs |
| `forensics.analyze_holder_distribution` | Gini coefficient, top-10 concentration, tier breakdown |
| `forensics.detect_bundle_activity` | Find transaction clusters in same slot (MEV/bundle detection) |
| `forensics.get_token_creation_info` | Trace back to token mint creation transaction |

## Supporting Operations

| Category | Operations |
|----------|------------|
| **wallets** | `get_wallet_token_holdings`, `get_wallet_sol_transfers` |
| **trading** | `get_token_trades`, `get_wallet_swaps` |
| **tokens** | `get_token_largest_accounts`, `get_token_supply`, `get_signatures_for_address` |
| **transactions** | `get_parsed_transactions`, `get_transaction_history` |
| **balances** | `get_sol_balance`, `get_token_accounts` |
| **accounts** | `get_account_info`, `get_multiple_accounts` |
| **assets** | `get_asset`, `get_assets_by_owner`, `search_assets`, `get_asset_proof` |
| **fees** | `get_priority_fee` |
| **webhooks** | `create_webhook`, `list_webhooks`, `delete_webhook` |
| **programs** | `get_program_accounts` |

## Usage

The server exposes 4 meta-tools:

```
solana_forensics_discover()      # Browse all operations
solana_forensics_get_schema(op)  # Get parameter details
solana_forensics_execute(op, {}) # Execute operation
solana_forensics_continue()      # Continue paginated results
```

### Example: Trace Funding Sources

```
solana_forensics_execute("forensics.trace_sol_funding", {
    "address": "TARGET_WALLET",
    "max_hops": 3
})
```

### Example: Detect Wash Trading

```
solana_forensics_execute("forensics.detect_wash_trading", {
    "mint": "TOKEN_MINT_ADDRESS",
    "limit": 100
})
```

### Example: Find Common Funding Across Wallets

```
solana_forensics_execute("forensics.find_common_funding", {
    "addresses": ["WALLET_1", "WALLET_2", "WALLET_3"],
    "max_hops": 2
})
```

### Example: Analyze Token Holder Distribution

```
solana_forensics_execute("forensics.analyze_holder_distribution", {
    "mint": "TOKEN_MINT_ADDRESS"
})
```

## Requirements

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
- Helius API key (free tier works)

## Data Provider

Powered by [Helius API](https://helius.dev) for Solana blockchain data access.