@three-ws/kol-mcp

v0.1.0

Published

5 days ago

Track one smart trader from any AI agent — a tracked KOL wallet's portfolio P&L (realized/unrealized, win rate, top holding) and its trades on a given mint. Read-only over the live public three.ws KOL API. No key, no signer, no payment.

0High
0Medium
0Low

three-ws

mcp three.ws solana kol smart-money portfolio pnl copy-trading

A Model Context Protocol server for the per-wallet KOL deep dive. Where @three-ws/intel-mcp ranks the whole tracked KOL set (kol_leaderboard) and shows everyone's trades on a mint (kol_trades), this server zooms in on one smart trader: pull their live portfolio P&L card, then inspect their own buys/sells of a specific token — everything an agent needs to decide whether to copy or analyze them.

Portfolio P&L comes from the three.ws Birdeye proxy (the Birdeye key lives server-side); trade history comes from the three.ws Helius-backed KOL feed. All live, read-only — no API key, signer, or payment on the client. Point THREE_WS_BASE at a deployment and go.

Install

npm install @three-ws/kol-mcp

Or run with npx (no install):

npx @three-ws/kol-mcp

Quick start

Claude Code, one line:

claude mcp add kol -- npx -y @three-ws/kol-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"kol": {
			"command": "npx",
			"args": ["-y", "@three-ws/kol-mcp"]
		}
	}
}

Inspect the surface with the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx @three-ws/kol-mcp

Tools

| Tool | Type | What it does | | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | | get_wallet_portfolio | read-only | One KOL wallet's live portfolio P&L card: realized P&L, unrealized (open-position) P&L, win rate, total trades, top holding. | | get_wallet_trades | read-only | That wallet's recent buys/sells of a given mint — side, SOL size, token amount, price, USD value, and timing, newest first. |

Both tools read live data: portfolio P&L and trade feeds move between calls, so neither is idempotent.

Input parameters

get_wallet_portfolio — wallet (required).

get_wallet_trades — wallet (required), mint (required), limit (1–100, default 20).

The three.ws trade feed is mint-keyed (it scans every tracked KOL wallet for activity on one mint), so a per-wallet view is that feed narrowed to your wallet. get_wallet_trades therefore needs both a wallet and a mint. To see every tracked wallet's trades on a mint, use kol_trades in @three-ws/intel-mcp.

Example

// get_wallet_portfolio
> { "wallet": "5xY…KoL" }
{
  "ok": true,
  "wallet": "5xY…KoL",
  "has_activity": true,
  "realized_pnl_usd": 124300,
  "unrealized_pnl_usd": 38120,
  "win_rate": 0.64,
  "total_trades": 412,
  "top_token": { "symbol": "THREE", "pnl": 38120 }
}

// get_wallet_trades
> { "wallet": "5xY…KoL", "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "limit": 3 }
{
  "ok": true,
  "wallet": "5xY…KoL",
  "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
  "count": 2,
  "trades": [
    { "side": "buy", "amountSol": 4.2, "amountToken": 1830000, "price": 0.0000022, "usd": 612.4, "time": "2026-06-24T09:12:03.000Z", "source": "kol", "label": "Top Trader" }
  ]
}

has_activity: false on a portfolio (all-zero P&L, no trades, no holding) means the proxy has no recorded history for that address yet — an honest "no data", not a failure.

Requirements

Node.js >= 20.
Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

| Variable | Required | Default | | --------------------- | -------- | ------------------ | | THREE_WS_BASE | no | https://three.ws | | THREE_WS_TIMEOUT_MS | no | 20000 |

No key on the client: the Birdeye key that backs portfolio P&L and the Helius key behind the trade feed both live server-side on three.ws.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme