three.ws Activity

io.github.nirholas/activity-mcp

Documentation

@three-ws/activity-mcp

What's hot on three.ws right now — trending agents and coins, the $THREE holder leaderboard with tiers, and the site-wide activity ticker, from any AI agent.

A Model Context Protocol server that gives any AI assistant the three.ws live discovery surface over stdio. See which agents are trending by real chat activity, which coins the Oracle has the highest conviction in, where a wallet sits on the $THREE holder leaderboard, what each holder tier means, and what's happening across the platform right now — all live, read-only, no key required.

Every ranking, tier, and event comes straight from the public three.ws API. No API key, no signer, no payment — point THREE_WS_BASE at a deployment and go.

Install

npm install @three-ws/activity-mcp

Or run with npx (no install):

npx @three-ws/activity-mcp

Quick start

Claude Code, one line:

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

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

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

Inspect the surface with the MCP Inspector:

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

Tools

Tool	Type	What it does
`get_trending_agents`	read-only	Agents ranked by real chat activity over a 24h / 7d / all window — optionally blending wallet-trust reputation.
`get_trending_coins`	read-only	Coins ranked by the Oracle's 0–100 conviction score, with momentum/pedigree/structure/narrative sub-scores.
`get_holder_leaderboard`	read-only	The $THREE holder board ranked by on-chain balance, with tiers, the live market strip, and a "you are #N" lookup.
`get_tier_info`	read-only	The $THREE holder tier ladder — each band's label, minimum balance, and badge accent.
`get_feed_events`	read-only	The site-wide activity ticker — coin buys, agent deploys, level-ups, payments, and more, newest-first.

All five tools read live data: rankings, the holder board, and the feed all move between calls, so none are idempotent.

Input parameters

get_trending_agents — window (24h | 7d | all, default 24h), sort (activity | trust, default activity), limit (1–20, default 10).

get_trending_coins — limit (1–20, default 10).

get_holder_leaderboard — limit (1–100, default 50), offset (default 0), wallet (optional base58 — adds the wallet's own you standing).

get_tier_info — no parameters.

get_feed_events — limit (1–100, default 30).

Example

// get_trending_agents
> { "window": "7d", "limit": 2 }
{
  "ok": true,
  "window": "7d",
  "sort": "activity",
  "generated_at": "2026-06-24T12:00:00.000Z",
  "count": 2,
  "agents": [
    {
      "rank": 1,
      "id": "…",
      "name": "Luna",
      "description": "A 3D companion agent",
      "avatar_thumbnail_url": "https://…",
      "chat_count": 18420,
      "window_chats": 2310,
      "is_onchain": true,
      "agent_url": "https://three.ws/agent/…",
      "reputation": { "score": 82, "tier": "trusted", "tierLabel": "Trusted", "isNew": false }
    }
  ]
}

// get_holder_leaderboard
> { "limit": 1, "wallet": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" }
{
  "ok": true,
  "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump",
  "total": 4821,
  "supply": 1000000000,
  "decimals": 6,
  "holders": [
    { "rank": 1, "wallet": "…", "wallet_short": "AbCd…wXyZ", "amount": 42000000, "pct_of_supply": 0.042, "tier": "genesis" }
  ],
  "tiers": [ { "id": "genesis", "label": "Genesis", "min": 10000000, "accent": "#f5d0a9" } ],
  "market": { "price_usd": 0.0031, "market_cap": 3100000, "holders": 4821 },
  "you": { "rank": 137, "amount": 25400, "pct_of_supply": 0.0000254, "tier": "gold" }
}

The $THREE holder leaderboard is for $THREE — the only coin three.ws ranks holders for (CA FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump). The trending-coins list is the platform's runtime launch-directory discovery data: a ranking of what the Oracle scored, never a recommendation of any coin.

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`