@three-ws/portfolio-mcp

An AI agent's own trading state over MCP — portfolio value, PnL, live balances, the public trade feed, and one real write: a signed on-chain Solana transfer.

A Model Context Protocol server that gives an AI agent programmatic access to its own trading state over stdio: what it holds, how that value moves over time, a single token's position with live market data, the platform-wide feed of closed trades and their realized PnL, live on-chain balances for any wallet — and one real write, a signed Solana transfer of SOL or any SPL token.

Reads hit the live three.ws API and Solana RPC — nothing is mocked. The account-scoped reads run against the agent wallets you own (resolved from your three.ws session). The one write, send_transfer, signs locally with your own key and moves real funds on mainnet.

Install

npm install @three-ws/portfolio-mcp

Or run with npx (no install):

npx @three-ws/portfolio-mcp

Quick start

Claude Code, one line:

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

Claude Desktop / Cursor (claude_desktop_config.json or 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 is only needed for the account-scoped reads; SOLANA_SECRET_KEY is only needed for send_transfer. The trade feed and on-chain balance reads work with no configuration at all.

Inspect the surface with the MCP Inspector:

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

Tools

Everything reads live state — balances, feeds, and broadcasts all move between calls — so no tool is idempotent. send_transfer is the only tool that mutates anything.

Input parameters

get_portfolio_summary — snapshot (bool, default false — also persist a history point).

get_portfolio_history — days (1–365, default 90).

get_portfolio_asset: chain (solana | evm, required), id (native or the base58 mint / 0x contract, required), days (1 to 365, default 30), chain_id (optional EVM chain id: 8453 Base, 1 Ethereum, 42161 Arbitrum, 10 Optimism, 137 Polygon, 56 BNB, and the other chains the platform indexes). Leave chain_id off and the API prices the contract on whatever chain your wallets hold it on, defaulting to Base; set it when the same address exists on more than one chain.

get_trades_feed — network (mainnet | devnet, default mainnet), window (1h | 6h | 24h | 7d | 30d | all, default 24h), min_pnl_pct (default 10), limit (1–80, default 40), cursor (ISO timestamp for pagination), mint (filter to one coin).

get_wallet_balances — address (base58, required), include_tokens (bool, default true).

send_transfer — recipient (base58, required), amount (decimal string, required), mint (base58 SPL mint; omit / native for SOL), secret (base58, overrides SOLANA_SECRET_KEY), priorityMicroLamports (0–50,000,000), confirm (must be true to execute).

Realized vs. live value

Two different questions, two different tools:

• "What am I worth right now?" → get_portfolio_summary / get_portfolio_asset — live holdings priced in USD.
• "How have my closed trades done?" → get_trades_feed — realized PnL per closed position (entry/exit in SOL, profit %, multiple, hold time).

The write tool — send_transfer

send_transfer broadcasts a real, irreversible transaction on Solana mainnet and moves funds out of the signing wallet. It signs locally with the per-call secret or SOLANA_SECRET_KEY — the three.ws API never holds your key. Guardrails:

• confirm: true required while REQUIRE_CONFIRM is on (the default) — the first call without it returns a refusal, not a broadcast.
• MAX_SOL_PER_TX caps native SOL sends (default 0.5 SOL).
• RECIPIENT_ALLOWLIST, when set, restricts the destination to a known set.
• The mint is runtime input — pass the $THREE mint or any SPL token you hold. No mint is hardcoded.

For an SPL transfer it reads the mint's decimals on-chain, verifies your balance, and auto-creates the recipient's associated token account when missing. On a confirmation timeout it returns tx_unconfirmed with the signature rather than silently retrying — check Solscan before resending to avoid a double-spend.

Requirements

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

Environment variables

THREE_WS_SESSION is the value of the __Host-sid cookie from a signed-in three.ws browser session. Treat it — and SOLANA_SECRET_KEY — like a password.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0. See LICENSE.

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

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/portfolio-mcp is one package from it.

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