three.ws KOL

io.github.nirholasPublished by GitHub account nirholasv0.1.2Updated Oct 24, 2026

Per-wallet KOL deep dive — a tracked trader's portfolio P&L and its trades on a given mint.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Read-only MCP server that lets an assistant inspect one tracked KOL trader's Solana wallet: portfolio, on-chain P&L and trades on a given mint.

What you can do
  • Read a single KOL wallet's live portfolio card: holdings value, position count, top holding, 30-day realized P&L, win rate, trade count and volume
  • List that wallet's recent buys and sells of a specific mint, with side, SOL size, token amount, price, USD value and timing, newest first
  • Distinguish a quiet wallet (no recorded activity) from a provider outage, which is reported as an upstream error rather than an empty card
When to use it
Useful when an assistant needs to evaluate a specific smart-money trader on Solana before deciding whether to copy or analyze them, or to check what one wallet did with a particular token. For ranking the whole tracked KOL set or seeing every wallet's trades on a mint, a companion intel server is the better fit.
Requirements
Node.js 20 or newer, run locally via npx or npm install. Network access to the three.ws API; optional THREE_WS_BASE to point at another deployment and THREE_WS_TIMEOUT_MS for per-request timeout. No client API key is needed.
Before you install
All tools are read-only, so nothing can be signed, spent or published. Wallet addresses and mint addresses you query are sent to the three.ws service, which proxies holdings and trade data from third-party providers. P&L figures are computed by the service and can be null when no history exists; treat them as informational, not investment advice.

Installation

In SourceWeft

  1. Open three.ws KOL in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[three.ws]

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

[npm] [license] [node] [MCP Registry] [three.ws]

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

bash
npm install @three-ws/kol-mcp

Or run with npx (no install):

bash
npx @three-ws/kol-mcp

Quick start

Claude Code, one line:

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

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

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

Inspect the surface with the MCP Inspector:

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

Tools

ToolTypeWhat it does
get_wallet_portfolioread-onlyOne 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_tradesread-onlyThat 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

jsonc
// 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"}
jsonc
// 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/:

bash
node examples/list-tools.mjs     # both tools with their full input schemasnode 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

VariableRequiredDefault
THREE_WS_BASEnohttps://three.ws
THREE_WS_TIMEOUT_MSno20000

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.

Links

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub

Source: packages/kol-mcp/README.md at commit c8f2cde

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.2LatestOct 10, 2026
  2. v0.1.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts