three.ws KOL

@three-ws/kol-mcp

追踪一位聪明的交易者：从任意 AI Agent 查看已追踪的 KOL 钱包持仓、真实链上盈亏，以及其在指定 mint 上的交易。

---

一个用于深入分析单个钱包 KOL 的 Model Context Protocol 服务。 @three-ws/intel-mcp 可为所有已追踪的 KOL 排名（kol_leaderboard），并展示他们在某个 mint 上的交易（kol_trades）；而此服务聚焦于一位聪明的交易者：获取其实时投资组合卡片（持仓及真实链上盈亏），然后查看其对某个特定代币的买入／卖出记录，为 Agent 提供决定是否跟单或分析所需的一切信息。

持仓数据来自 three.ws 的 Birdeye 代理（Birdeye 密钥保存在服务端）；盈亏根据钱包自身的链上交易通过 FIFO 计算，交易历史则来自 three.ws 基于 Helius 的 KOL 信息流。所有数据均为实时只读：客户端无需 API 密钥、签名器或付款。将 THREE_WS_BASE 指向某个部署即可开始使用。

安装

npm install @three-ws/kol-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/kol-mcp

快速开始

Claude Code，只需一行：

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

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

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

使用 MCP Inspector 检查可用功能：

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

工具

工具	类型	功能
get_wallet_portfolio	只读	单个 KOL 钱包的实时投资组合卡片：持仓价值、持仓数量和最大持仓，以及根据其链上交易计算的 30 天已实现盈亏、胜率、交易次数和交易量。
get_wallet_trades	只读	该钱包近期对指定 mint 的买入／卖出记录——方向、SOL 数量、代币数量、价格、美元价值和时间，按时间从新到旧排列。

两个工具读取的都是实时数据：持仓、盈亏和交易信息流会在调用之间变化，因此都不具幂等性。

输入参数

get_wallet_portfolio —— wallet（必填）。

get_wallet_trades —— wallet（必填）、mint（必填）、limit（1–100，默认值为 20）。

three.ws 交易信息流以 mint 为键（会扫描每个已追踪的 KOL 钱包，查找某个 mint 上的活动），因此单钱包视图就是从该信息流中筛选出指定钱包的记录。get_wallet_trades 因此需要同时提供 wallet 和 mint。如需查看所有已追踪钱包在某个 mint 上的全部交易，请使用 @three-ws/intel-mcp 中的 kol_trades。

示例

// 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（没有持仓，也没有交易）表示该地址尚无记录历史：诚实地说明“没有数据”，而不是操作失败。P&L 字段为 null 且 pnl_source: null，同样是字段层面的诚实体现：three.ws 在该时间窗口内没有这个钱包的交易历史，因此不报告任何数据，而不是报告一个会被理解为持平记录的零。

服务中断绝不会伪装成上述任一情况。持仓提供方不可用或触发速率限制时，three.ws 会省略该钱包的行，而不是凭空编造一行；get_wallet_portfolio 会以 upstream_unavailable 失败，而不是返回一张空卡片。钱包没有活动和提供方不可用是两种不同的情况，复制交易者的 Agent 必须能够区分它们。

示例

可运行的示例位于 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

这两个示例都会通过 stdio 启动此服务，并读取实时的公开 KOL API。这里的所有工具 都是只读的，因此无法签名、花费资金或发布内容。预期输出请参阅 examples/README.md。

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。

环境变量

变量	必需	默认值
THREE_WS_BASE	否	https://three.ws
THREE_WS_TIMEOUT_MS	否	20000

客户端无需密钥：为持仓部分提供支持的 Birdeye 密钥，以及交易动态背后的 Helius 密钥，都存放在 three.ws 服务器端。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件的一部分 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}