# cryptopunks-mcp-server

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

An [MCP](https://modelcontextprotocol.io) server that connects AI assistants like Claude directly to the [NODE Foundation](https://nodefoundation.com) 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](https://deconstruct-lab.net).

---

## 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](https://modelcontextprotocol.io) — the open standard that lets AI assistants use external tools. Everything is read-only. Nothing touches your wallet.

---

## Quick start

### Install & build

```bash
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`:

```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

```bash
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](https://cryptopunks.app/llms.txt) |
| Collection Bids | `https://bids.cryptopunks.app/api/v1` | None | [Swagger](https://bids.cryptopunks.app/docs) |

Both APIs are operated by the [NODE Foundation](https://nodefoundation.com) and are publicly accessible with no API key required.

---

## Credits

**API** — [NODE Foundation](https://nodefoundation.com) (CryptoPunks API, launched March 2026)
**Server** — [DECONSTRUCT LAB](https://deconstruct-lab.net)
**Protocol** — [Model Context Protocol](https://modelcontextprotocol.io) by [Anthropic](https://anthropic.com)

---

## License

MIT