clash-mcp

---

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

npm install @three-ws/clash-mcp

Or run with npx (no install):

npx @three-ws/clash-mcp

Quick start

Claude Code, one line:

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

Claude Desktop / Cursor (claude_desktop_config.json or mcp.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:

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

Tools

Tool	Type	What it does
get_clash_state	read-only	The live battle board: matchups, each army's power + momentum, the round clock, the tug-of-war share, who's leading.
get_clash_leaderboard	read-only	All-time faction war records (W/L/D, win rate, power), optionally a single faction's top soldiers this round.
enlist_faction	write	Prove the signer's wallet holds a faction coin (Solana-signed) and get a war pass.
rally_faction	write	Spend 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

// 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
}

// 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

Variable	Required	Default	Notes
THREE_WS_BASE	no	https://three.ws	API deployment to talk to.
THREE_WS_TIMEOUT_MS	no	20000	Per-request timeout.
SOLANA_SECRET_KEY	writes only	—	Base58 secret of the enlisting wallet. Per-call secret overrides it. Treat like cash.
CLASH_SOLANA_SECRET	no	—	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):

error	Meaning	Recovery
validation_error	Bad arguments: a missing faction token, or rally_faction called with neither a pass nor a token.	Fix the call.
no_signer / invalid_secret	A write tool had no Solana key, or the key was not a base58 64-byte secret.	Pass secret or set SOLANA_SECRET_KEY.
not_eligible	The 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_error	The 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.
timeout	No response within THREE_WS_TIMEOUT_MS.	Retry or raise the timeout.
network_error	The request never reached the API (DNS, offline, TLS).	Check connectivity / THREE_WS_BASE.
bad_config	THREE_WS_TIMEOUT_MS is not a positive number (thrown at startup).	Fix the env var.

Links

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

---

Support the project

If clash-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/clash-mcp and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors

Star history

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

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