cryptopunks-mcp-server

Ask your AI about any CryptoPunk — and get real answers from live data.

An MCP server that connects AI assistants like Claude directly to the NODE Foundation CryptoPunks API. Look up any punk, check the floor, analyze a wallet, scan collection bids, research rarity — all through conversation. 28 tools, zero wallet setup, no API keys.

Built by DECONSTRUCT LAB.

---

Why this exists

If you collect CryptoPunks, research the market, or track wallets — you already know the data is scattered across dashboards, block explorers, and manual lookups. This server puts all of it inside your AI assistant.

Once installed, you can ask Claude (or any MCP-compatible AI) questions about the CryptoPunks market in plain English and get answers drawn from live on-chain data. No more tab-switching between cryptopunks.app, Etherscan, and spreadsheets. Your AI becomes your research desk.

Under the hood, this wraps the NODE Foundation's public CryptoPunks API (launched March 2026) through the Model Context Protocol — the open standard that lets AI assistants use external tools. Everything is read-only. Nothing touches your wallet.

---

Quick start

Install & build

git clone https://github.com/Deconstruct2021/cryptopunks-mcp-server.git
cd cryptopunks-mcp-server
npm install
npm run build

Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cryptopunks": {
      "command": "node",
      "args": ["/absolute/path/to/cryptopunks-mcp-server/dist/index.js"]
    }
  }
}

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop. You should see 28 tools available.

Connect to Claude Code

claude mcp add cryptopunks node /absolute/path/to/cryptopunks-mcp-server/dist/index.js

Requirements

• Node.js ≥ 18
• No API keys needed
• No wallet needed

---

What you can ask

Once connected, just talk to your AI. Here are real examples organized by what you're trying to do:

For collectors

"What's the current floor price? Show me the cheapest punk for sale."

"Tell me everything about Punk #7804 — type, traits, owner, full history."

"What punks does vitalik.eth own? What have they bought and sold?"

"Are there any collection bids on my punk #3100 right now?"

For market researchers

"Show me the last 50 sales. What's the average price this week?"

"Who are the top 10 holders? How concentrated is ownership?"

"What are the rarest trait combinations? How many 0-attribute punks exist?"

"Compare the sale history of all 9 Alien punks."

For bid infrastructure & developers

"Generate a Merkle root for punks [100, 200, 300, 400, 500] and prove punk #300 is in the set."

"What are the highest active collection bids right now? Who's bidding and on what?"

"Get the Merkle proofs for bid d1b94d62-7217-4e48-b501-2dc8f4342627 — I need them for settlement."

---

Tools (28)

Punk Data (6)

Tool	What it returns
get_punk	Owner, type, attributes, price, bid status. Auto-corrects type for non-human punks.
get_punk_details	Full details + optional transaction history (uses reliable POST endpoint).
get_punk_metadata	Lightweight metadata — most accurate type classification (Alien/Ape/Zombie/Male/Female).
get_punk_image_url	1024×1024 PNG URL. Supports transparent bg, custom colors, and status overlays.
get_punk_traits	Trait list with accurate type data.
get_punk_history	Complete transaction history from initial 2017 claim through every transfer, sale, bid, and offer.

Market Intelligence (9)

Tool	What it returns
get_floor_price	Current floor price in ETH. Falls back to floor punk data if primary endpoint is stale.
get_floor_punk	The cheapest punk currently listed — full details.
get_recent_sales	Last N sales with buyer, seller, price in wei/USD, timestamps. Max 50.
get_top_sales	All-time highest sales ranked by value.
get_all_offers	All listed punks. ⚠️ Upstream API may 500 — server returns helpful error with alternatives.
get_all_native_bids	All punks with active on-chain bids (native contract bids, not collection bids).
get_market_stats	Full market overview: floor, listed count, recent sales, top sales, bid activity.
get_attribute_stats	Trait distribution across all 10,000 punks — enables rarity analysis.
get_leaderboard	Top holders ranked by number of punks owned.

Account Analytics (1)

Tool	What it returns
get_account	The power tool. Full portfolio for any wallet or ENS name: owned punks, for-sale listings, bids placed & received, complete buy/sell history, realized PnL, total volume. Works for your own wallet or anyone else's.

Batch Operations (1)

Tool	What it returns
get_batch_recent_history	Recent transaction history for up to 50 punks in a single call.

Collection Bids (6)

Tool	What it returns
get_collection_bids	List bids with optional bidder/status filters. Returns summarized metadata.
get_top_collection_bids	Highest active bids by amount. Defaults to pending status.
get_all_collection_bids	All bids chronologically, up to 1000.
get_collection_bid_by_id	Full details for a single bid by UUID.
get_collection_bids_for_punk	All collection bids that cover a specific punk.
get_bid_proofs	Merkle proofs for every punk in a bid — required for on-chain settlement.

Merkle Tree (5)

Tool	What it returns
generate_merkle_root	Compute a Merkle root for any set of punk indices. Pure math, no wallet.
generate_merkle_proof	Proof that a specific punk is in a set. For on-chain bid settlement.
verify_merkle_proof	Verify a single proof against a root.
generate_batch_proofs	Proofs for multiple punks in one call. More efficient than repeated single calls.
verify_batch_proofs	Batch-verify multiple proofs against a root.

---

Architecture

src/
├── api.ts       — Typed fetch wrappers for cryptopunks.app + bids.cryptopunks.app
├── tools.ts     — 28 Zod input schemas with agent-friendly descriptions
├── handlers.ts  — Tool dispatch, response formatting, workarounds for upstream quirks
└── index.ts     — MCP server bootstrap with Zod validation on every call

Design principles:

• Passthrough over transformation — raw API data is preserved. The server adds corrections (type enrichment, floor price fallback) but never hides or filters data.
• Summarize for safety — collection bid responses are automatically summarized to stay under the MCP 1MB tool result limit. Full data is always available via get_bid_proofs.
• Fail transparently — when upstream endpoints break, the server returns structured errors with specific alternative tools to try.

---

Known issues

These are upstream API issues, not bugs in this server. Each one is handled gracefully.

Issue	Impact	Server behavior
get_all_offers returns HTTP 500	Can't list all offered punks	Returns clean error suggesting get_market_stats and get_floor_punk
get_punk returns wrong type for non-humans	Alien/Ape/Zombie punks misclassified as Male	Auto-enriches from get_punk_metadata; falls back with warning
get_floor_price primary endpoint returns "0"	Floor price appears null	Falls back to get_floor_punk and extracts offer value
Collection bid payloads exceed 1MB	MCP tool result limit hit	Auto-summarizes: strips punk index arrays, keeps metadata
get_top_collection_bids empty without filter	No bids returned	Defaults to status: "pending"

---

Roadmap

v1.1 (planned)

• Response normalization for get_floor_punk (flat structure with friendly field names)
• Bid count metadata on collection bid list endpoints
• Enhanced get_punk enrichment (full trait overlay)

v2.0 (future)

Wallet and signing tools — deferred from v1.0 to keep the install story frictionless:

• submit_collection_bid — Submit an EIP-712 signed collection bid
• refresh_collection_bids — Sync on-chain nonce state for a bidder
• generate_bid_struct — Generate the EIP-712 signing payload

These require a deployed stash contract on-chain and wallet configuration.

---

APIs wrapped

API	Base URL	Auth	Docs
CryptoPunks Data	https://cryptopunks.app/api	None	llms.txt
Collection Bids	https://bids.cryptopunks.app/api/v1	None	Swagger

Both APIs are operated by the NODE Foundation and are publicly accessible with no API key required.

---

Credits

API — NODE Foundation (CryptoPunks API, launched March 2026) Server — DECONSTRUCT LAB Protocol — Model Context Protocol by Anthropic

---

License

MIT