nftdata-mcp

nftdata-mcp

一个 MCP 服务，可将 NFT Data API 作为单个工具提供给 AI 客户端（Claude Desktop、Cursor 等）。它会自动处理 x402 支付流程。

• npm： https://www.npmjs.com/package/nftdata-mcp
• MCP Registry： https://registry.modelcontextprotocol.io/?q=nftdata

工具

get_collection_data

通过一次调用返回 OpenSea 收藏品市场数据。

参数	类型	描述
collection	string	OpenSea 收藏品 slug，来自 opensea.io/collection/<slug>（例如 azuki）

返回字段：name、slug、contracts、floor_price、floor_price_currency、one_day_sales、one_day_volume、seven_day_sales、seven_day_volume、thirty_day_sales、thirty_day_volume、total_sales、total_volume、num_owners、total_supply、created_date。交易量和价格的币种会在对应的 *_currency 字段中给出（ETH、USDC、HYPE 等）。

每次调用费用为 $0.002（在 Base 上以 USDC 支付，通过 x402 完成）。

要求

• Node.js 20+
• 一个已充值少量 Base 上 USDC 的钱包私钥

请使用余额较少的专用钱包。切勿使用主钱包。

快速开始（npx）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "nftdata": {
      "command": "npx",
      "args": ["-y", "nftdata-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x..."
      }
    }
  }
}

重启 Claude Desktop，然后可以提问，例如：“azuki 的地板价和 7 天交易量是多少？”

从源代码运行

npm install

仅为当前 shell 会话设置密钥，然后启动：

# macOS / Linux
export EVM_PRIVATE_KEY=0x...
npm start

# Windows PowerShell
$env:EVM_PRIVATE_KEY = "0x..."
npm start

:: Windows cmd
set EVM_PRIVATE_KEY=0x...
npm start

服务会在 stdin 上等待 MCP 客户端，因此手动运行时不会显示任何输出；它应由 MCP 客户端启动。

要通过 Claude Desktop 使用本地检出版本，请将 args 指向 ["tsx", "/absolute/path/to/nftdata-mcp/server.ts"]，并设置 "command": "npx"。

构建

npm run build   # compiles server.ts and lib.ts to dist/
npm test        # offline unit tests, no network and no payments

配置

变量	必需	默认值	描述
EVM_PRIVATE_KEY	是	–	用于支付调用费用的钱包私钥（0x + 64 个十六进制字符）
NFTDATA_MAX_REQUESTS	否	100	每个会话最多签署的支付次数。整数范围为 1–1000；其他值会导致启动时报错
NFTDATA_TIMEOUT_MS	否	15000	请求超时时间，单位为毫秒（1000–60000）
NFTDATA_URL	否	https://www.nftdata.app/api/get-collection-data	仅接受 NFT Data 官方端点（www.nftdata.app 或 nftdata.app）；其他值会导致启动停止

行为

• 发送 POST /api/get-collection-data，请求体为 {"collection": "<slug>"}。
• slug 会先去除首尾空格并转换为小写，然后必须符合 ^[a-z0-9][a-z0-9_-]*$（最多 100 个字符）；否则不会发送请求。
• x402 客户端仅注册 Base 主网（eip155:8453）。签署前会检查每个支付挑战：方案为 exact，网络为 Base 主网，代币为 Base 上的 USDC，金额恰好为 2000 个最小单位（$0.002），且收款方必须为 0x344143199642e87320785823c20c2df107d17534。任何不符合条件的挑战都会被拒绝，不予签署。
• 每笔已签署的支付都会计入 NFTDATA_MAX_REQUESTS，包括之后失败或超时的请求所对应的支付。
• 不会自动重试：一次工具调用最多尝试支付一次。
• 按 slug 缓存成功响应 5 分钟。并发的相同调用会共用同一个进行中的请求。
• 对 400（slug 无效）、404（未找到收藏品）、429（速率限制，附带 Retry-After）、超时及其他失败，返回通用错误；不会将服务端和支付详情传递给 MCP 客户端。

限制

• 仅支持 Base 上的 x402。此封装尚未实现 Solana 和 MPP 支付方式。
• 预期的收款地址硬编码在 lib.ts 中。如果 NFT Data 的收款地址发生变化，请更新 OFFICIAL_PAY_TO 并发布新版本。
• 支付钩子（server.ts）依赖已安装的 @x402/* SDK，且不在离线测试的覆盖范围内。
• x402 客户端库变化很快；如果导入失败，请查看当前的 x402 文档。

API 参考

• OpenAPI：https://www.nftdata.app/openapi.json
• 文档：https://www.nftdata.app/docs