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)

Market Intelligence (9)

Account Analytics (1)

Batch Operations (1)

Collection Bids (6)

Merkle Tree (5)

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.

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

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