three.ws Portfolio

@three-ws/portfolio-mcp

通过 MCP 获取 AI Agent 自身的交易状态——投资组合价值、盈亏、实时余额、公开交易动态，以及一项真正的写入操作：签名并在 Solana 链上转账。

---

一个 Model Context Protocol 服务，通过 stdio 为 AI Agent 提供对其自身交易状态的程序化访问：持有哪些资产、这些资产的价值如何随时间变化、单个代币的持仓及实时市场数据、平台范围内已平仓交易的动态及其已实现盈亏、任意钱包的实时链上余额，以及一项真正的写入操作：使用 SOL 或任意 SPL 代币进行签名的 Solana 转账。

读取操作会访问实时 three.ws API 和 Solana RPC——没有任何模拟数据。账户级读取会针对你拥有的 Agent 钱包执行（从你的 three.ws 会话中解析）。唯一的写入操作 send_transfer 会使用你自己的密钥在本地签名，并在主网上转移真实资金。

安装

npm install @three-ws/portfolio-mcp

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

npx @three-ws/portfolio-mcp

快速开始

Claude Code，只需一行：

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

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

{
	"mcpServers": {
		"portfolio": {
			"command": "npx",
			"args": ["-y", "@three-ws/portfolio-mcp"],
			"env": {
				"THREE_WS_SESSION": "<your __Host-sid cookie>",
				"SOLANA_SECRET_KEY": "<base58 secret of the sending wallet>"
			}
		}
	}
}

账户级读取才需要 THREE_WS_SESSION；只有使用 send_transfer 时才需要 SOLANA_SECRET_KEY。交易动态和链上余额读取无需任何配置即可使用。

使用 MCP Inspector 检查功能：

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

工具

工具	类型	功能
get_portfolio_summary	读取 · 会话	汇总你拥有的所有 Agent 钱包中的实时持仓和美元价值，并按钱包细分。可选快照。
get_portfolio_history	读取 · 会话	根据存储的快照查看你的投资组合美元总价值随时间的变化——即业绩图表。
get_portfolio_asset	读取 · 会话	深入查看单个代币：哪些钱包持有该代币、你的总数量和美元价值，以及实时市场数据和价格历史图表。
get_trades_feed	读取 · 公开	平台范围内已平仓头寸及其已实现盈亏的动态——最新退出的排在最前，并可按币种筛选。
get_wallet_balances	读取 · 公开	从 RPC 直接获取任意 Solana 地址上实时的链上 SOL 和 SPL（包括 Token-2022）余额。
send_transfer	写入 · 有破坏性	从你自己的钱包签名并广播真实、不可撤销的 Solana 主网转账，支持 SOL 或任意 SPL 代币。

所有读取都会获取实时状态——余额、动态和广播结果都会随调用而变化——因此没有任何工具是幂等的。send_transfer 是唯一会修改数据的工具。

输入参数

get_portfolio_summary — snapshot（布尔值，默认 false — 同时保存一个历史点）。

get_portfolio_history — days（1–365，默认 90）。

get_portfolio_asset：chain（solana | evm，必填）、id（native 或 base58 铸币地址 / 0x 合约地址，必填）、days（1–365，默认 30）、chain_id（可选的 EVM 链 ID：8453 Base、1 Ethereum、42161 Arbitrum、10 Optimism、137 Polygon、56 BNB，以及平台索引的其他链）。省略 chain_id 时，API 会在你的钱包持有该合约的任意链上为其定价，默认使用 Base；当同一地址存在于多条链上时，请设置此参数。

get_trades_feed — network（mainnet | devnet，默认 mainnet）、window（1h | 6h | 24h | 7d | 30d | all，默认 24h）、min_pnl_pct（默认 10）、limit（1–80，默认 40）、cursor（用于分页的 ISO 时间戳）、mint（筛选单个币种）。

get_wallet_balances — address（base58，必填）、include_tokens（布尔值，默认 true）。

send_transfer — recipient（base58，必填）、amount（十进制字符串，必填）、mint（base58 SPL 铸币地址；省略或设为 native 表示 SOL）、secret（base58，覆盖 SOLANA_SECRET_KEY）、priorityMicroLamports（0–50,000,000）、confirm（必须为 true 才会执行）。

已实现价值与实时价值

两个不同的问题，对应两种不同的工具：

• “我现在的资产价值是多少？” → get_portfolio_summary / get_portfolio_asset — 以 USD 计价的实时持仓。
• “我的已平仓交易表现如何？” → get_trades_feed — 每笔已平仓头寸的已实现 PnL（以 SOL 计价的入场 / 退出价格、利润率、倍数、持有时间）。

写入工具 — send_transfer

send_transfer 会在 Solana 主网上广播一笔真实且不可逆的交易，并从签名钱包转出资金。它使用每次调用传入的 secret 或 SOLANA_SECRET_KEY 在本地签名 — three.ws API 不会持有你的密钥。安全措施：

• 启用 REQUIRE_CONFIRM 时（默认开启）必须设置 confirm: true — 首次未设置此参数的调用会返回拒绝信息，而不会广播交易。
• MAX_SOL_PER_TX 限制原生 SOL 转账金额（默认 0.5 SOL）。
• 设置 RECIPIENT_ALLOWLIST 后，目标地址将限制为已知地址集合中的地址。
• mint 是运行时输入 — 传入 $THREE 铸币地址或你持有的任意 SPL 代币。代码中未硬编码任何铸币地址。

对于 SPL 转账，工具会读取链上铸币地址的小数位数、验证你的余额，并在收款方缺少关联代币账户时自动创建该账户。确认超时时，工具会返回带有签名的 tx_unconfirmed，而不会悄悄重试 — 重新发送前请先检查 Solscan，以免重复支出。

要求

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

环境变量

变量	必需	默认值
THREE_WS_BASE	否	https://three.ws
THREE_WS_TIMEOUT_MS	否	20000
THREE_WS_SESSION	用于账户级读取	—
SOLANA_RPC_URL	否	https://api.mainnet-beta.solana.com
SOLANA_SECRET_KEY	用于 send_transfer	—
MAX_SOL_PER_TX	否	0.5
RECIPIENT_ALLOWLIST	否	—（允许任何有效公钥）
REQUIRE_CONFIRM	否	true

THREE_WS_SESSION 是已登录的 three.ws 浏览器会话中的 __Host-sid Cookie 值。请像保护密码一样保护它和 SOLANA_SECRET_KEY。

链接

• 主页：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}