spirit-cards-mcp

A read-only Model Context Protocol (MCP) server for Spirit Cards (Proof of Card) — a proof-of-work minted collectible card game on Robinhood Chain — mainnet chainId 4663, live since 2026-10-05.

It runs over stdio, so Claude Desktop and Cursor can launch it with npx. It fetches live game data from the hosted web API and computes the proof-of-work locally with viem — so an agent can inspect the collection, verify a nonce, or even grind a valid nonce, without a wallet, a private key, or a single transaction.

Read-only. No keys, no secrets, no signing, no sending. Every network call is a plain GET.

---

Quick start

Run with npx (after publishing)

npx spirit-cards-mcp

Run from source

npm install
node src/index.mjs      # starts the stdio server (logs to stderr)

The server speaks MCP over stdin/stdout and logs only to stderr — it is normally launched by an MCP client, not by hand.

---

Use in Claude Desktop

Add this to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "spirit-cards": {
      "command": "npx",
      "args": ["-y", "spirit-cards-mcp"],
      "env": { "SPIRIT_CARDS_API": "https://spiritcards.fun" }
    }
  }
}

Use in Cursor

Add this to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "spirit-cards": {
      "command": "npx",
      "args": ["-y", "spirit-cards-mcp"],
      "env": { "SPIRIT_CARDS_API": "https://spiritcards.fun" }
    }
  }
}

---

Configuration

Env var	Default	Meaning
SPIRIT_CARDS_API	https://spiritcards.fun	Base URL of the hosted site/API

All data endpoints are read-only GETs:

• /.well-known/ai.json — project descriptor (chain id, core contract, mechanics, links)
• /stats/current.json — live supply, price, required difficulty (baseBits), cooldown
• /api/meta/{tokenId} — card metadata
• /api/points — points leaderboard
• /api/pool — staking pool / emissions snapshot (accrued pool, split shares, vault weight)
• /api/recent — recent on-chain activity

---

Tools

Tool	Args	Description
get_project_info	—	/.well-known/ai.json + a composed human summary
get_collection_stats	—	Live stats: supply, price, baseBits, cooldown, paused flag
get_card	tokenId	Card metadata (/api/meta/{tokenId})
get_leaderboard	limit? (default 25)	Points leaderboard, trimmed to limit
get_pool	—	Staking pool: accrued pool, split shares, vault weight (undistributed)
get_recent_activity	limit? (default 10)	Recent events, trimmed to limit
verify_nonce	miner, nonce	Verify a nonce's work locally (no tx): {work, leadingZeroBits, valid}
find_nonce	miner, maxAttempts? (≤5M)	Grind nonce 0.. until valid (~20 s wall cap)
get_mining_guide	—	Step-by-step mint guide with live price/difficulty/cooldown

Proof-of-work

A nonce is valid when:

work = keccak256(abi.encodePacked(uint256 chainId, address core, address miner, uint256 nonce))
leadingZeroBits(work) >= baseBits

Both verify_nonce and find_nonce compute this locally with viem's keccak256 over concatHex([chainId, core, miner, nonce]) — byte-for-byte identical to Solidity's abi.encodePacked.

Prompts

Prompt	Args	Description
project_overview	—	Introduce the game to a newcomer (calls the info + stats tools)
start_mining	wallet?	Walk through finding a nonce and the exact mint transaction

---

Hosted HTTP MCP

Prefer HTTP over stdio? The same server is also hosted at:

https://spiritcards.fun/api/mcp

---

License

MIT © 2026 Spirit Cards (Proof of Card). See LICENSE.