nftdata-mcp

NFT Data MCP

NFT Data MCP es un servidor MCP publicado (paquete npm nftdata-mcp) que le proporciona a un agente de IA una herramienta, get_collection_data. Dado un slug de colección de OpenSea, devuelve una instantánea estructurada de los datos de mercado de esa colección desde la API de NFT Data. Cada llamada exitosa y no almacenada en caché se paga automáticamente en USDC en la red principal de Base.

Recursos oficiales:

• Repositorio: https://github.com/Nomad07/nftdata-mcp
• npm: https://www.npmjs.com/package/nftdata-mcp
• Documentación de la API: https://www.nftdata.app/docs
• Documentación del servidor MCP: https://www.nftdata.app/docs/mcp

Cuándo usar esta habilidad

Úsala cuando el usuario quiera estadísticas de mercado actuales para una o más colecciones NFT específicas que estén listadas en OpenSea, por ejemplo:

• el precio mínimo de una colección
• recuentos de ventas y volumen de comercio en las últimas 24 horas, 7 días, 30 días o durante toda la vida
• la(s) dirección(es) del contrato y la(s) cadena(s) de una colección
• suministro total, número de propietarios únicos o fecha de creación
• una comparación lado a lado de varias colecciones

No lo uses para nada fuera de los límites enumerados en "Limitaciones" más abajo.

Prerrequisitos: el servidor MCP ya debe estar configurado

Esta habilidad no instala ni configura nada. El servidor nftdata-mcp ya debe estar ejecutándose en el cliente MCP del usuario, y la herramienta get_collection_data debe estar disponible.

Si la herramienta no está disponible:

1. Dile al usuario que el servidor NFT Data MCP no está conectado.
2. Dirígelo a la guía de configuración en https://www.nftdata.app/docs/mcp o al README en https://github.com/Nomad07/nftdata-mcp.
3. Detente. No intentes solucionarlo de otra manera, y no le pidas al usuario que pegue una clave privada en la conversación (ver "Seguridad de la billetera").

Como referencia, el servidor es configurado por el usuario, en su propia máquina, con una configuración MCP stdio como esta (la clave permanece en la configuración local del usuario y nunca se comparte con el agente):

{
  "mcpServers": {
    "nftdata": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "EVM_PRIVATE_KEY": "<establecido por el usuario localmente>"
      }
    }
  }
}

Requisitos: Node.js 20 o más reciente, un cliente MCP que admita servidores stdio y una billetera EVM dedicada que tenga una pequeña cantidad de USDC en la red principal de Base.

La herramienta: get_collection_data

El servidor expone exactamente una herramienta.

Entrada

{ "collection": "azuki" }

• collection (cadena, obligatorio): el slug de la colección de OpenSea. Es la última parte de la URL de OpenSea de la colección: opensea.io/collection/<slug>.
• El servidor recorta y convierte el slug a minúsculas. Luego debe comenzar con una letra o dígito y contener solo letras minúsculas, dígitos, - y _ (máximo 100 caracteres). Cualquier otra cosa es rechazada antes de que se realice cualquier solicitud o pago.
• Solo se aceptan slugs. Los nombres de visualización de colecciones, direcciones de contratos, IDs de token, direcciones de billetera y URLs completas no son entradas válidas. Si el usuario da una URL, extrae el slug de ella. Si el usuario da solo un nombre, pide el slug o la URL de OpenSea; no adivines.

Salida

Un objeto JSON (devuelto como texto) con los campos siguientes. Para una llamada recién pagada, el servidor agrega dos líneas después del JSON: Payment: 0x... (el hash de la transacción) y Verify: https://basescan.org/tx/0x.... Los resultados almacenados en caché no incluyen estas líneas. Lee la parte JSON para los datos y trata las dos líneas como un recibo de pago.

Campo	Significado
name	Nombre de visualización de la colección
slug	Slug de la colección de OpenSea
contracts	Arreglo de objetos { "address", "chain" }
floor_price	Precio mínimo actual (número)
floor_price_currency	Moneda del precio mínimo (por ejemplo ETH, USDC, HYPE)
one_day_sales, seven_day_sales, thirty_day_sales	Recuentos de ventas de las últimas 24 horas, 7 días, 30 días
one_day_volume, seven_day_volume, thirty_day_volume	Volumen de comercio para esos períodos
one_day_volume_currency, seven_day_volume_currency, thirty_day_volume_currency	Moneda de cada volumen
total_sales, total_volume	Recuento de ventas y volumen de por vida
total_volume_currency	Moneda del volumen de por vida
num_owners	Número de propietarios únicos
total_supply	Número total de tokens en la colección
created_date	Fecha de creación de la colección (fecha ISO 8601, por ejemplo 2022-01-12)

Los datos provienen de la API de OpenSea y se transmiten tal como se devuelven. Es una instantánea puntual, no una serie temporal.

Ejemplo de respuesta (histórica, no datos en vivo)

{
  "name": "Azuki",
  "slug": "azuki",
  "contracts": [{ "address": "0xed5af388653567af2f388e6224dc7c4b3241c544", "chain": "ethereum" }],
  "floor_price": 0.49328599,
  "floor_price_currency": "ETH",
  "one_day_sales": 21,
  "one_day_volume": 10.150091000000002,
  "seven_day_sales": 163,
  "seven_day_volume": 96.67526161112121,
  "thirty_day_sales": 471,
  "thirty_day_volume": 325.72023569476767,
  "total_sales": 93156,
  "total_volume": 831992.6461159982,
  "num_owners": 4394,
  "total_supply": 10000,
  "created_date": "2022-01-12",
  "one_day_volume_currency": "ETH",
  "seven_day_volume_currency": "ETH",
  "thirty_day_volume_currency": "ETH",
  "total_volume_currency": "ETH"
}

Interpretación y comparación de resultados

Sigue estas reglas para que la respuesta se mantenga fiel a los datos:

1. Informa solo lo que se devolvió. Si falta un campo o es null (por ejemplo total_supply, created_date o una moneda de volumen), di que no estaba disponible. Nunca inventes un valor ni llenes un vacío de memoria u otras fuentes sin decirlo.
2. Un valor faltante no es cero. null o un campo ausente significa "desconocido". Un 0 devuelto significa cero. No los trates igual y no incluyas valores desconocidos en sumas o promedios como si fueran cero.
3. Siempre empareja un número con su moneda. Lee floor_price_currency y cada campo *_volume_currency. Las monedas difieren según la colección (ETH, USDC, HYPE y otras). Nunca etiquetes un precio como ETH o USD a menos que la respuesta lo diga.
4. No mezcles monedas en aritmética o clasificaciones. La herramienta no proporciona tipos de cambio. Al comparar colecciones, compara números directamente solo si sus campos de moneda coinciden. Si difieren, muestra cada valor con su propia moneda y di que una comparación directa necesita una conversión que los datos no incluyen.
5. Etiqueta los números derivados. Las cifras que calcules, como el precio de venta promedio (volumen dividido por ventas, solo cuando las ventas son mayores que 0 y se conoce la moneda del volumen) o la participación del volumen de por vida en los últimos 30 días, son tus propios cálculos. Di que son derivados y muestra las entradas.
6. Mantén el contexto de la cadena. contracts[].chain muestra dónde reside la colección. Una colección puede listar más de un contrato. No asumas una sola cadena o un solo contrato.
7. No sobreinterpretes. Los datos son una instantánea de una consulta. No describas tendencias, impulso, precios "buenos" o "malos", ni des consejos de inversión. Puedes señalar diferencias simples entre períodos (por ejemplo, que el volumen de 7 días es mayor que el volumen de 24 horas) sin predecir nada.
8. Di cuándo se obtuvieron los datos. Los datos del mercado cambian continuamente. Si un resultado se reutiliza dentro de una conversación, recuérdale al usuario que es una instantánea.
9. Respeta el redondeo. Los valores sin procesar tienen muchos decimales. Puedes redondear para facilitar la lectura, pero no cambies los números originales ni impliques más precisión de la que tienen los datos.

Cuando se te pida cambiar la presentación (resumen, tabla, informe, comparación), reformatea los mismos valores sin alterarlos.

Uso consciente del costo

• Cada llamada no almacenada en caché cuesta $0.002 USDC. Los resultados se almacenan en caché durante 5 minutos por slug; pedir el mismo slug nuevamente dentro de esa ventana es gratis y devuelve los datos en caché sin un nuevo recibo de pago.
• Las llamadas concurrentes idénticas comparten una solicitud, por lo que las búsquedas duplicadas no pagan dos veces.
• El servidor limita las llamadas pagadas por sesión (NFTDATA_MAX_REQUESTS, predeterminado 100, máximo 1000). No llames a la herramienta en bucles o para búsquedas especulativas. Para comparaciones, obtén cada colección solicitada una vez.
• Antes de un lote grande (por ejemplo, más de un puñado de colecciones), dile al usuario cuántas llamadas se necesitan y el costo total, y obtén su aprobación.
• No reintentes automáticamente una llamada fallida. El servidor nunca reintenta por su cuenta, y después de un tiempo de espera, es posible que ya se haya firmado un pago. Informa el error y deja que el usuario decida.

Manejo de errores

Situación	Qué hacer
Mensaje de slug inválido	Verifica el slug con la URL de OpenSea; pídele al usuario que lo confirme. No se realizó ningún pago.
"Colección no encontrada"	El slug no coincide con una colección en OpenSea. Pide el slug o la URL correctos.
Mensaje de límite de velocidad (con un retraso en segundos)	Espera el tiempo indicado antes de intentar nuevamente e informa al usuario.
"Pago rechazado por la política de seguridad"	El servidor rechazó los términos de pago antes de firmar. Infórmalo; no intentes evitarlo.
"El pago no fue aceptado"	La API no aceptó el pago. Infórmalo; no reintentes por tu cuenta.
"límite de solicitudes pagadas ... alcanzado"	Se alcanzó el límite de gasto de la sesión. El usuario debe reiniciar el cliente o aumentar NFTDATA_MAX_REQUESTS.
Tiempo de espera	Es posible que se haya autorizado un pago y no se haya reintentado. Dile al usuario; ofrécete a intentarlo de nuevo solo si está de acuerdo.
Error genérico "La solicitud falló."	Infórmalo como un error. No adivines la causa.

Ejemplos de indicaciones

• "Usa el servidor NFT Data MCP. ¿Cuál es el precio mínimo de la colección azuki?"
• "Obtén las estadísticas de mercado de basedpunks: precio mínimo, ventas y volumen de 24h, 7d y 30d, suministro y propietarios."
• "¿Qué dirección de contrato y cadena usa milady en OpenSea?"
• "Compara azuki y basedpunks por precio mínimo y volumen de 30 días. Solo compara números que usen la misma moneda."
• "Aquí está el enlace de OpenSea: https://opensea.io/collection/azuki. Resume la colección como un informe breve."
• "Muestra la respuesta JSON sin procesar para azuki y explica cada campo."
• "¿Cuántos propietarios tiene azuki en comparación con su suministro total?" (una proporción derivada, así que etiquétala como derivada)

Detalles de pago

• Precio: $0.002 USDC por llamada exitosa no almacenada en caché.
• Red: solo red principal de Base (eip155:8453), pagado en USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). La red de pago es la red principal de Base independientemente de la cadena de bloques en la que se encuentre la colección consultada. Consultar una colección en otra cadena, incluidas las colecciones de Solana listadas en OpenSea, aún paga en Base.
• Protocolo predeterminado: x402 v2. El servidor paga un desafío USDC exact en la red principal de Base.
• Protocolo opcional: MPP evm/charge. Seleccionado solo cuando el servidor se inicia con NFTDATA_PAYMENT_PROTOCOL=mpp. Paga el mismo precio, en USDC en la red principal de Base.
• Un protocolo por ejecución del servidor, sin respaldo. El protocolo se elige una vez cuando se inicia el servidor. El servidor nunca cambia de uno a otro, nunca intenta ambos para una sola llamada y nunca reintenta con el otro. Si la API no ofrece un pago aceptable en el protocolo seleccionado, no se firma nada y la llamada falla. Un valor NFTDATA_PAYMENT_PROTOCOL no válido (cualquier cosa que no esté vacío, x402 o mpp) detiene el servidor al inicio.
• Verificaciones antes de firmar: el servidor verifica la red, el token, el esquema o método, el monto exacto (2000 unidades atómicas, que son $0.002) y la dirección del receptor oficial antes de firmar cualquier cosa. Un desafío que no coincida es rechazado.
• Como máximo un intento de pago por llamada a la herramienta.
• Los aciertos de caché son gratuitos. No activan un pago ni incluyen un hash de transacción.
• Recibos: cada llamada exitosa recién pagada incluye un hash de transacción y un enlace a BaseScan que el usuario puede abrir para verificar el pago.
• No confundas el servidor con la API principal. La API de NFT Data acepta x402 v2 en las redes principales de Base y Solana, y MPP evm/charge en la red principal de Base. Este servidor MCP es más limitado: paga solo en la red principal de Base, con x402 v2 o MPP evm/charge, uno a la vez. El servidor MCP no admite pagos de Solana.

Seguridad de la billetera

• Nunca le pidas al usuario que comparta, pegue, escriba o envíe una clave privada, frase semilla o archivo de billetera en la conversación, y nunca solicites una para "configurar" o "reparar" el servidor. La clave se establece solo por el usuario, localmente, en el entorno del servidor MCP (EVM_PRIVATE_KEY).
• No leas, imprimas, copies ni resumas archivos de configuración o variables de entorno que puedan contener la clave.
• Si un usuario pega una clave privada en el chat de todos modos, no la repitas ni la uses. Dile que deje de usar esa billetera, mueva cualquier fondo a una nueva billetera y reemplace la clave.
• Recomienda una billetera dedicada que contenga solo un saldo pequeño de USDC en la red principal de Base, nunca una billetera principal o una con fondos significativos.
• Anima a verificar los pagos en BaseScan usando el hash de transacción del recibo.
• Nunca sugieras enviar fondos a una dirección que no te haya sido proporcionada por la propia billetera del usuario o la documentación oficial.

Limitaciones

Esta habilidad y el servidor son búsquedas de datos de colección de solo lectura. No son:

• una herramienta de búsqueda o descubrimiento general de NFT: sin búsqueda por nombre, rasgo, rareza, rango de precios o clasificación, y sin listas de colecciones "principales" o "de moda"
• una herramienta a nivel de token: sin búsqueda de NFT individual, ID de token, metadatos, rareza o propiedad
• una herramienta de billetera: sin saldos de billetera, tenencias, cartera o historial de transacciones
• una herramienta de comercio o transacciones: no puede comprar, vender, listar, ofertar, acuñar, transferir, puentear o intercambiar nada, y nunca mueve fondos excepto el pequeño pago por llamada
• un feed histórico o en tiempo real: devuelve una instantánea por llamada, sin historial de precios o actualizaciones en streaming
• un oráculo de precios o asesor: sin conversión de moneda, valoración, predicciones o consejos de inversión

Otros límites:

• Solo se pueden consultar colecciones que existan en OpenSea, y la entrada debe ser el slug de OpenSea.
• Algunos campos pueden faltar o ser null para algunas colecciones.
• Los datos provienen de OpenSea y se informan tal como se reciben; esta herramienta no verifica, corrige ni complementa los datos.
• El servidor no admite pagos de Solana, ni ningún otro protocolo o red de pago que no sean x402 v2 o MPP evm/charge en la red principal de Base.
• La herramienta no puede ejecutarse sin una billetera configurada con USDC en la red principal de Base.
• No se puede utilizar para colecciones que no estén en OpenSea (incluidas aquellas solo en mercados como Blur, LooksRare o X2Y2), y no puede buscar por nombre de colección o dirección de contrato (solo slug).
• La política de límites de velocidad y la disponibilidad de la API de OpenSea afectan los resultados; los límites de velocidad pueden retrasar las respuestas.
• El caché es de 5 minutos por slug; las solicitudes más frecuentes incurren en tarifas de pago.
• El servidor tiene un límite de solicitudes pagadas por sesión (predeterminado 100, máximo 1000 configurable).

Notas finales

• Esta habilidad no proporciona acceso a ninguna otra herramienta del servidor; el servidor NFT Data MCP tiene exactamente una herramienta (get_collection_data).
• Siempre que sea posible, usa el slug exacto de la URL de OpenSea para evitar errores y pagos desperdiciados.
• Para comparaciones, recuerda verificar las monedas y nunca mezclar monedas en sumas o clasificaciones.
• Para obtener la información más actualizada sobre el precio, el volumen y la disponibilidad del servicio, consulta la documentación oficial de la API: https://www.nftdata.app/docs y la documentación del servidor MCP: https://www.nftdata.app/docs/mcp.