Ask your AI about any CryptoPunk — and get real answers from live data.
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.ethown? 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 |
Tools (16)
get_punkReturns owner, type, attributes, price, and bid status for a specific punk.get_punk_detailsReturns full details and transaction history for a punk.get_punk_metadataReturns lightweight metadata including accurate type classification.get_punk_image_urlReturns a 1024x1024 PNG URL for a punk.get_punk_traitsReturns a list of traits for a specific punk.get_punk_historyReturns complete transaction history for a punk.get_floor_priceReturns the current floor price in ETH.get_floor_punkReturns full details of the cheapest punk currently listed.get_recent_salesReturns the last N sales with buyer, seller, price, and timestamps.get_top_salesReturns all-time highest sales ranked by value.get_all_offersReturns all listed punks.get_all_native_bidsReturns all punks with active on-chain bids.get_market_statsReturns a full market overview including floor, listed count, and sales.get_attribute_statsReturns trait distribution across all 10,000 punks.get_leaderboardReturns top holders ranked by number of punks owned.get_accountReturns full portfolio for any wallet or ENS name.Configuration
{"mcpServers": {"cryptopunks": {"command": "node", "args": ["/absolute/path/to/cryptopunks-mcp-server/dist/index.js"]}}}