three.ws Coin Clash

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

Play three.ws Coin Clash — read the faction battle board and leaderboard, enlist, and rally.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

A local MCP server that lets an assistant read the live three.ws Coin Clash faction battle board and leaderboard, and enlist or rally a Solana wallet for a side

What you can do
Read the live battle board: matchups, army power and momentum, round clock and tug-of-war share, and who is leading. Read all-time faction war records (wins, losses, draws, win rate, power) and a faction's top soldiers this round. Enlist a wallet by signing a challenge and proving an on-chain holding of the faction coin, receiving a war pass. Rally battle power for a faction by spending taps, either with a war pass or by auto-enlisting with a token in one call.
When to use it
Use it when you want an assistant to follow or take part in the three.ws Coin Clash community faction war: scouting the current round, checking standings, or enlisting and rallying a wallet that holds a faction coin. Reads alone are enough for tracking; writes need a funded holding.
Requirements
Node.js 20 or newer, run locally via npx or npm. Network access to the three.ws API, configurable with THREE_WS_BASE and THREE_WS_TIMEOUT_MS. Writes need a base58 Solana secret key for a wallet that holds the faction coin, supplied through SOLANA_SECRET_KEY, the CLASH_SOLANA_SECRET fallback, or a per-call secret argument.
Before you install
SOLANA_SECRET_KEY (or CLASH_SOLANA_SECRET) is a wallet secret key and should be treated like cash; prefer a per-call secret or a dedicated environment on a trusted machine. The key is used only to sign the enlist challenge locally, not transactions, and no funds move. Rally calls append power and are not idempotent, so repeated calls change standings.

Installation

In SourceWeft

  1. Open three.ws Coin Clash 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/clash-mcp

Play three.ws Coin Clash — the community faction war backed by real holdings + pump.fun data — from any AI agent. Read the live battle board, enlist your wallet, and rally power for a faction.

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

A Model Context Protocol server that puts Coin Clash — three.ws's community faction war — in reach of any AI agent over stdio. Every community is a faction, its holders are its army; two factions are matched each round, and whichever army rallies more power before the clock runs out wins. Read the live board and leaderboard, then enlist (prove you hold the coin) and rally for your side.

Reads are public — point THREE_WS_BASE at a deployment and go. Writes are wallet-scoped: enlisting signs a challenge with your Solana key and the backend confirms a live on-chain holding of the faction coin before issuing a war pass. Factions, members, and momentum come from CoinCommunities + pump.fun; rally power is persisted and ranked server-side. Nothing is mocked.

Install

bash
npm install @three-ws/clash-mcp

Or run with npx (no install):

bash
npx @three-ws/clash-mcp

Quick start

Claude Code, one line:

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

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

json
{	"mcpServers": {		"clash": {			"command": "npx",			"args": ["-y", "@three-ws/clash-mcp"],			"env": {				"SOLANA_SECRET_KEY": "<base58 secret of your enlisting wallet — only needed for writes>"			}		}	}}

Inspect the surface with the MCP Inspector:

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

Tools

ToolTypeWhat it does
get_clash_stateread-onlyThe live battle board: matchups, each army's power + momentum, the round clock, the tug-of-war share, who's leading.
get_clash_leaderboardread-onlyAll-time faction war records (W/L/D, win rate, power), optionally a single faction's top soldiers this round.
enlist_factionwriteProve the signer's wallet holds a faction coin (Solana-signed) and get a war pass.
rally_factionwriteSpend taps as battle power for your faction — pass a war pass, or a token to auto-enlist and rally in one call.

The reads return live data — power and standings move between calls, so neither is idempotent. The writes are wallet-scoped: no funds ever move (a war pass is a signed proof, not a transaction), so neither is destructive. enlist_faction is idempotent (re-enlisting mints an equivalent pass); rally_faction is not (each call appends power).

Input parameters

get_clash_state — none.

get_clash_leaderboard — faction (optional mint; also returns that faction's top soldiers this round).

enlist_faction — token (required faction mint), secret (optional base58 Solana secret; falls back to SOLANA_SECRET_KEY).

rally_faction — taps (required, 1–50), and either pass (a war pass from enlist_faction) or token (+ optional secret) to auto-enlist first.

How a battle works

  1. Scout. get_clash_state shows the current round: who's matched, each army's power, momentum, and msLeft.
  2. Enlist. enlist_faction issues a challenge bound to your wallet + faction, signs it with your Solana key, and the backend verifies the signature and a live on-chain holding of the coin. You get back a warPass. (No holding → eligible:false, reason:"not_a_holder".)
  3. Rally. rally_faction spends taps (1–50 per call) from the pass as battle power — multiplied by the faction's live momentum, capped per wallet per round. Call it repeatedly while msLeft > 0.
  4. Win. When the round clock hits zero, the army with more power takes the battle and the result is written to each faction's all-time war record (get_clash_leaderboard).

Example

jsonc
// get_clash_state> {}{  "ok": true,  "epoch": 486231,  "epochMs": 3600000,  "endsAt": 1750000000000,  "msLeft": 1843000,  "factionCount": 16,  "arena": [    {      "id": "486231:…",      // each side also carries image, posts, and priceUsd (elided here)      "a": { "token": "…", "symbol": "ALPHA", "members": 8200, "momentum": 1.31, "power": 940, "record": { "w": 12, "l": 4, "d": 1, "battles": 17, "power": 8100 } },      "b": { "token": "…", "symbol": "BETA",  "members": 5100, "momentum": 1.12, "power": 610, "record": { "w": 7,  "l": 9, "d": 0, "battles": 16, "power": 5400 } },      "aShare": 0.61,      "leader": "…ALPHA mint…"    }  ],  "bye": null}
jsonc
// rally_faction — auto-enlist + rally in one call (wallet must hold the coin)> { "token": "…faction mint…", "taps": 50 }{  "ok": true,  "enlisted": { "wallet": "…", "amount": 1250000, "usd": 84.20 },  "epoch": 486231,  "mint": "…faction mint…",  "added": 66,  "momentum": 1.31,  "walletPower": 66,  "walletCap": 5000,  "capped": false,  "factionPower": 1005,  "msLeft": 1841000}

Requirements

  • Node.js >= 20.
  • Network access to https://three.ws (or your own THREE_WS_BASE).
  • For writes only: a base58 Solana secret whose wallet holds the faction coin it enlists for, via SOLANA_SECRET_KEY or the per-call secret arg.

Environment variables

VariableRequiredDefaultNotes
THREE_WS_BASEnohttps://three.wsAPI deployment to talk to.
THREE_WS_TIMEOUT_MSno20000Per-request timeout.
SOLANA_SECRET_KEYwrites only—Base58 secret of the enlisting wallet. Per-call secret overrides it. Treat like cash.
CLASH_SOLANA_SECRETno—Fallback signer read when SOLANA_SECRET_KEY is unset, for hosts that scope env vars per server. Same format and the same care.

The secret is only ever used to sign the enlist challenge locally — a detached ed25519 signature over the challenge text. It never signs a transaction and no funds move. Still, it controls a wallet: prefer a per-call secret or a dedicated env on a machine you trust.

Errors

A failed tool call returns an MCP error result (isError: true) whose text is a single JSON object: { "ok": false, "error": "<code>", "message": "…" }, plus status on upstream rejections and detail where the failure carries context (e.g. which wallet was not a holder):

errorMeaningRecovery
validation_errorBad arguments: a missing faction token, or rally_faction called with neither a pass nor a token.Fix the call.
no_signer / invalid_secretA write tool had no Solana key, or the key was not a base58 64-byte secret.Pass secret or set SOLANA_SECRET_KEY.
not_eligibleThe auto-enlisting wallet does not hold the faction coin, so no pass was issued. detail carries wallet, faction, and reason.Hold the coin, then retry.
upstream_errorThe API rejected the request. status carries the HTTP code; notable bodies include bad_challenge, bad_signature, pass_invalid (expired or foreign war pass), balance_unavailable (RPC could not read the holding), and cc_unconfigured (the deployment has no CoinCommunities config).Act on the code; re-enlist on pass_invalid.
timeoutNo response within THREE_WS_TIMEOUT_MS.Retry or raise the timeout.
network_errorThe request never reached the API (DNS, offline, TLS).Check connectivity / THREE_WS_BASE.
bad_configTHREE_WS_TIMEOUT_MS is not a positive number (thrown at startup).Fix the env var.

Links

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

Source: packages/clash-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.3LatestOct 10, 2026
  2. v0.1.2Sep 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