wax-mcp-full

v0.1.0 — a local-first MCP server for the WAX blockchain.

It lets an AI host (Claude Desktop, Cursor, Grok Build, …) query accounts, chain state, AtomicAssets / AtomicMarket, Hyperion history, and WAXP prices, and prepare unsigned transactions for a wallet to sign. No API keys. Mainnet and testnet.

This is an early public release. It is more complete than the archived yksanjo/wax-mcp-server (8 tools, single RPC, dead v1 history). It is not a 1.0.

Features

Area	What you get
Account	WAXP + token balances, CPU/NET/RAM, permissions, account info
Chain	get_info, get_block, get_table_rows, ABI summary
History	Hyperion /v2 actions + transaction (not v1 history)
AtomicAssets	assets, templates, schemas, collections, mints, transfers
AtomicMarket	sales, auctions, buy offers, stats, price history, recent sales, top collections
Market	WAXP price + market data (CoinGecko → CoinPaprika)
Health	multi-endpoint status
Safe writes	unsigned transfer / stake / unstake / vote / Atomic transfer+burn + simulate
Signing	off by default — use a wallet

Also registers resources (wax://account/{name}, …) and prompts (inspect-account, market-overview, …).

Requirements

• Node.js 20+
• HTTPS access to public WAX guild APIs (no keys)

Install

git clone https://github.com/eoinjosephcurran-code/wax-mcp-full.git
cd wax-mcp-full
npm install
npm run build
node dist/index.js --help

Dev (no build):

npx tsx src/index.ts --network mainnet

Add it to a host

Replace /ABSOLUTE/PATH/TO/wax-mcp-full with the folder you cloned.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "wax": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"],
      "env": { "WAX_NETWORK": "mainnet" }
    }
  }
}

Restart Claude Desktop.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "wax": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"]
    }
  }
}

Grok Build

~/.grok/config.toml:

[mcp_servers.wax]
command = "node"
args = ["/ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js"]
startup_timeout_sec = 30

Or: grok mcp add wax -- node /ABSOLUTE/PATH/TO/wax-mcp-full/dist/index.js

Copy-paste templates live in examples/.

Configuration

Variable	Meaning
WAX_NETWORK	mainnet (default) or testnet
WAX_RPC_URLS	Comma-separated HTTPS RPC URLs
WAX_ATOMIC_URLS	AtomicAssets / AtomicMarket hosts
WAX_HYPERION_URLS	Hyperion history hosts
WAX_LIGHT_URLS	Light API hosts
WAX_PRICE_URLS	CoinGecko / CoinPaprika bases
WAX_TIMEOUT_MS	Per-request timeout (default 12000, 1000–30000)
WAX_RETRIES	Retries per URL on transient errors (default 2)
WAX_TX_EXPIRE_SECONDS	Unsigned tx expiration (default 180)
WAX_ENABLE_SIGNING	Must be 1 and a key source to broadcast
WAX_KEYS_FILE	File of WIFs (one per line) — prefer this over env

CLI: --network mainnet\|testnet.

Only https URLs are accepted. Tools never take an RPC URL argument.

eosjs is not installed by default. Prefer a wallet. Local wax_sign_broadcast requires npm install eosjs plus WAX_ENABLE_SIGNING=1.

Safety

• Prepare tools return unsigned JSON. Sign in Anchor, WAX Cloud Wallet, or cleos.
• wax_simulate_transaction never broadcasts. Public RPCs often cannot dry-run unsigned JSON; then simulated is false.
• Never put a private key in chat or in a tool argument.

Example prompts

• “What is the WAXP price and 24h volume?”
• “Show CPU/NET/RAM and tokens for eosio.”
• “List recent AtomicMarket sales for alien.worlds.”
• “Prepare an unsigned transfer of 1.00000000 WAX from alice to bob — do not sign it.”

More in examples/example-prompts.md.

Tests

npm test           # unit + MCP smoke + live probes (skip-soft if offline)
npm run test:live  # live probes; fail if public APIs are down
npm run typecheck

Known limits (v0.1)

• Public Atomic / Hyperion nodes can be slow or rate-limit.
• Simulate is best-effort; many RPCs refuse unsigned JSON.
• MCP resources have no isError flag — failures are JSON inside a successful read.
• wax_get_block returns headers + transaction_count, not full transactions.
• Optional local signing is a footgun. Leave it off.

License

MIT