@three-ws/kol-mcp

Track one smart trader: a tracked KOL wallet's holdings, real on-chain P&L, and its trades on a given mint, from any AI agent.

license

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 card (holdings plus real on-chain P&L), then inspect their own buys/sells of a specific token: everything an agent needs to decide whether to copy or analyze them.

Holdings come from the three.ws Birdeye proxy (the Birdeye key lives server-side); P&L is FIFO-computed from the wallet's own on-chain trades, and 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 card: holdings value, position count and top holding, plus 30d realized P&L, win rate, trades and volume from its own on-chain trades.
`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: holdings, 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,
  "portfolio_value_usd": 38120,
  "holdings": 14,
  "top_token": { "symbol": "THREE", "valueUsd": 21500 },
  "realized_pnl_usd": 124300,
  "win_rate": 0.64,
  "total_trades": 412,
  "volume_usd": 2840000,
  "pnl_source": "onchain-fifo",
  "pnl_window": "30d"
}

// 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 (no holdings and no trades) means the proxy has no recorded history for that address yet: an honest "no data", not a failure. A null P&L field with pnl_source: null is the same kind of honesty at field level: three.ws has no trade history for that wallet in the window, so it reports nothing rather than a zero that would read as a flat record.

An outage is never dressed up as either of those. When the holdings provider is down or rate-limited, three.ws omits the wallet's row rather than inventing one, and get_wallet_portfolio fails with upstream_unavailable instead of answering with an empty card. A quiet wallet and a dark provider are different answers, and an agent copying a trader needs to be able to tell them apart.

Examples

Runnable examples live in examples/:

node examples/list-tools.mjs     # both tools with their full input schemas
node examples/wallet-card.mjs    # a trader's portfolio card + trades, live

Both spawn this server over stdio and read the live public KOL API. Every tool
here is read-only, so nothing can be signed, spent, or published. See
examples/README.md for expected output.

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 the holdings half and the Helius key behind the trade feed both live server-side on three.ws.

Part of three.ws

three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/kol-mcp is one package from it.

Documentation site: https://nirholas.github.io/kol-mcp/
npm: https://www.npmjs.com/package/@three-ws/kol-mcp
Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of packages/kol-mcp)
Agent-readable summary: llms.txt and AGENTS.md
Issues and ideas: https://github.com/nirholas/kol-mcp/issues

kol-mcp