NFT Data MCP
NFT Data MCP ist ein veröffentlichter MCP-Server (npm-Paket nftdata-mcp), der einem KI-Agenten ein Tool zur Verfügung stellt: get_collection_data. Mit einem OpenSea-Kollektion-Slug gibt es eine strukturierte Momentaufnahme der Marktdaten dieser Kollektion von der NFT Data API zurück. Jeder erfolgreiche, nicht zwischengespeicherte Aufruf wird automatisch in USDC auf dem Base-Mainnet bezahlt.
Offizielle Ressourcen:
- Repository: https://github.com/Nomad07/nftdata-mcp
- npm: https://www.npmjs.com/package/nftdata-mcp
- API-Dokumentation: https://www.nftdata.app/docs
- MCP-Server-Dokumentation: https://www.nftdata.app/docs/mcp
Wann dieses Skill verwenden
Verwenden Sie es, wenn der Benutzer aktuelle Marktstatistiken für eine oder mehrere bestimmte NFT-Kollektionen wünscht, die auf OpenSea gelistet sind, zum Beispiel:
- den Floor-Preis einer Kollektion
- Verkaufszahlen und Handelsvolumen der letzten 24 Stunden, 7 Tage, 30 Tage oder Lebenszeit
- die Vertragsadresse(n) und Kette(n) einer Kollektion
- Gesamtangebot, Anzahl eindeutiger Besitzer oder Erstellungsdatum
- einen direkten Vergleich mehrerer Kollektionen
Verwenden Sie es nicht für etwas außerhalb der unter "Einschränkungen" aufgeführten Grenzen.
Voraussetzungen: Der MCP-Server muss bereits eingerichtet sein
Dieses Skill installiert oder konfiguriert nichts. Der nftdata-mcp-Server muss bereits im MCP-Client des Benutzers laufen, und das Tool get_collection_data muss verfügbar sein.
Wenn das Tool nicht verfügbar ist:
- Teilen Sie dem Benutzer mit, dass der NFT Data MCP-Server nicht verbunden ist.
- Verweisen Sie ihn auf die Einrichtungsanleitung unter https://www.nftdata.app/docs/mcp oder die README unter https://github.com/Nomad07/nftdata-mcp.
- Stoppen Sie. Versuchen Sie nicht, es zu umgehen, und bitten Sie den Benutzer nicht, einen privaten Schlüssel in das Gespräch einzufügen (siehe "Wallet-Sicherheit").
Als Referenz wird der Server vom Benutzer auf seinem eigenen Rechner mit einer stdio-MCP-Konfiguration wie dieser eingerichtet (der Schlüssel bleibt in der lokalen Konfiguration des Benutzers und wird niemals mit dem Agenten geteilt):
{
"mcpServers": {
"nftdata": {
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"EVM_PRIVATE_KEY": "<vom Benutzer lokal gesetzt>"
}
}
}
}
Voraussetzungen: Node.js 20 oder neuer, ein MCP-Client, der stdio-Server unterstützt, und ein dediziertes EVM-Wallet mit einem kleinen Guthaben an USDC auf dem Base-Mainnet.
Das Tool: get_collection_data
Der Server stellt genau ein Tool zur Verfügung.
Eingabe
{ "collection": "azuki" }
collection(String, erforderlich): der OpenSea-Kollektion-Slug. Er ist der letzte Teil der OpenSea-URL der Kollektion:opensea.io/collection/<slug>.- Der Server trimmt den Slug und wandelt ihn in Kleinbuchstaben um. Er muss dann mit einem Buchstaben oder einer Ziffer beginnen und darf nur Kleinbuchstaben, Ziffern,
-und_enthalten (maximal 100 Zeichen). Alles andere wird abgewiesen, bevor eine Anfrage oder Zahlung erfolgt. - Es werden nur Slugs akzeptiert. Anzeigenamen von Kollektionen, Vertragsadressen, Token-IDs, Wallet-Adressen und vollständige URLs sind keine gültige Eingabe. Wenn der Benutzer eine URL angibt, extrahieren Sie den Slug daraus. Wenn der Benutzer nur einen Namen angibt, fragen Sie nach dem Slug oder der OpenSea-URL; raten Sie nicht.
Ausgabe
Ein JSON-Objekt (als Text zurückgegeben) mit den folgenden Feldern. Bei einem neu bezahlten Aufruf fügt der Server zwei Zeilen nach dem JSON an: Payment: 0x... (der Transaktions-Hash) und Verify: https://basescan.org/tx/0x.... Zwischengespeicherte Ergebnisse enthalten diese Zeilen nicht. Lesen Sie den JSON-Teil für die Daten und behandeln Sie die beiden Zeilen als Zahlungsbeleg.
| Feld | Bedeutung |
|---|---|
name | Anzeigename der Kollektion |
slug | OpenSea-Kollektion-Slug |
contracts | Array von { "address", "chain" }-Objekten |
floor_price | Aktueller Floor-Preis (Zahl) |
floor_price_currency | Währung des Floor-Preises (z. B. ETH, USDC, HYPE) |
one_day_sales, seven_day_sales, thirty_day_sales | Verkaufszahlen für die letzten 24 Stunden, 7 Tage, 30 Tage |
one_day_volume, seven_day_volume, thirty_day_volume | Handelsvolumen für diese Zeiträume |
one_day_volume_currency, seven_day_volume_currency, thirty_day_volume_currency | Währung jedes Volumens |
total_sales, total_volume | Lebenszeit-Verkaufszahlen und -Volumen |
total_volume_currency | Währung des Lebenszeit-Volumens |
num_owners | Anzahl eindeutiger Besitzer |
total_supply | Gesamtanzahl der Token in der Kollektion |
created_date | Erstellungsdatum der Kollektion (ISO 8601-Datum, z. B. 2022-01-12) |
Die Daten stammen von der OpenSea-API und werden so weitergegeben, wie sie zurückgegeben werden. Es handelt sich um eine Momentaufnahme zu einem bestimmten Zeitpunkt, nicht um eine Zeitreihe.
Beispielantwort (historisch, keine Live-Daten)
{
"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"
}
Interpretation und Vergleich von Ergebnissen
Befolgen Sie diese Regeln, damit die Antwort den Daten treu bleibt:
- Geben Sie nur das zurück, was zurückgegeben wurde. Wenn ein Feld fehlt oder
nullist (z. B.total_supply,created_dateoder eine Volumenwährung), sagen Sie, dass es nicht verfügbar war. Erfinden Sie niemals einen Wert und füllen Sie keine Lücken aus dem Gedächtnis oder anderen Quellen, ohne dies zu erwähnen. - Ein fehlender Wert ist nicht Null.
nulloder ein fehlendes Feld bedeutet "unbekannt". Ein zurückgegebenes0bedeutet Null. Behandeln Sie sie nicht gleich und beziehen Sie unbekannte Werte nicht in Summen oder Durchschnitte ein, als ob sie Null wären. - Paaren Sie eine Zahl immer mit ihrer Währung. Lesen Sie
floor_price_currencyund jedes*_volume_currency-Feld. Währungen unterscheiden sich je nach Kollektion (ETH,USDC,HYPEund andere). Bezeichnen Sie einen Preis niemals als ETH oder USD, es sei denn, die Antwort gibt dies an. - Mischen Sie keine Währungen in Berechnungen oder Ranglisten. Das Tool bietet keine Wechselkurse. Wenn Sie Kollektionen vergleichen, vergleichen Sie Zahlen nur direkt, wenn ihre Währungsfelder übereinstimmen. Wenn sie sich unterscheiden, zeigen Sie jeden Wert mit seiner eigenen Währung und sagen Sie, dass ein direkter Vergleich eine Umrechnung erfordert, die die Daten nicht enthalten.
- Kennzeichnen Sie abgeleitete Zahlen. Zahlen, die Sie berechnen, wie den durchschnittlichen Verkaufspreis (Volumen geteilt durch Verkäufe, nur wenn Verkäufe größer als 0 und die Volumenwährung bekannt sind) oder den Anteil des Lebenszeit-Volumens in den letzten 30 Tagen, sind Ihre eigenen Berechnungen. Sagen Sie, dass sie abgeleitet sind, und zeigen Sie die Eingaben.
- Behalten Sie den Kettenkontext bei.
contracts[].chainzeigt, wo die Kollektion lebt. Eine Kollektion kann mehr als einen Vertrag auflisten. Gehen Sie nicht von einer einzelnen Kette oder einem einzelnen Vertrag aus. - Interpretieren Sie nicht übermäßig. Die Daten sind eine Momentaufnahme einer einzigen Abfrage. Beschreiben Sie keine Trends, Dynamiken, "gute" oder "schlechte" Preise oder geben Sie Anlageberatung. Sie dürfen auf einfache Unterschiede zwischen Zeitfenstern hinweisen (z. B. dass das 7-Tage-Volumen größer ist als das 24-Stunden-Volumen), ohne etwas vorherzusagen.
- Sagen Sie, wann die Daten abgerufen wurden. Marktdaten ändern sich ständig. Wenn ein Ergebnis innerhalb eines Gesprächs wiederverwendet wird, erinnern Sie den Benutzer daran, dass es sich um eine Momentaufnahme handelt.
- Respektieren Sie das Runden. Rohwerte haben viele Dezimalstellen. Sie dürfen zur Lesbarkeit runden, aber ändern Sie die Quellenzahlen nicht und implizieren Sie keine höhere Genauigkeit, als die Daten haben.
Wenn Sie aufgefordert werden, die Darstellung zu ändern (Zusammenfassung, Tabelle, Bericht, Vergleich), formatieren Sie dieselben Werte neu, ohne sie zu verändern.
Kostenbewusste Nutzung
- Jeder nicht zwischengespeicherte Aufruf kostet $0,002 USDC. Ergebnisse werden für 5 Minuten pro Slug zwischengespeichert; die erneute Abfrage desselben Slugs innerhalb dieses Zeitraums ist kostenlos und gibt die zwischengespeicherten Daten ohne einen neuen Zahlungsbeleg zurück.
- Identische gleichzeitige Aufrufe teilen sich eine Anfrage, sodass doppelte Suchvorgänge nicht doppelt bezahlt werden.
- Der Server begrenzt kostenpflichtige Aufrufe pro Sitzung (
NFTDATA_MAX_REQUESTS, Standard 100, maximal 1000). Rufen Sie das Tool nicht in Schleifen oder für spekulative Suchvorgänge auf. Für Vergleiche rufen Sie jede angeforderte Kollektion einmal ab. - Vor einem großen Batch (z. B. mehr als eine Handvoll Kollektionen) teilen Sie dem Benutzer mit, wie viele Aufrufe benötigt werden und wie hoch die Gesamtkosten sind, und holen Sie eine Bestätigung ein.
- Wiederholen Sie einen fehlgeschlagenen Aufruf nicht automatisch. Der Server wiederholt niemals von selbst, und nach einem Timeout kann eine Zahlung bereits signiert worden sein. Melden Sie den Fehler und lassen Sie den Benutzer entscheiden.
Fehlerbehandlung
| Situation | Was zu tun ist |
|---|---|
| Ungültige Slug-Meldung | Überprüfen Sie den Slug anhand der OpenSea-URL; bitten Sie den Benutzer, ihn zu bestätigen. Es wurde keine Zahlung geleistet. |
| "Collection not found" | Der Slug stimmt mit keiner Kollektion auf OpenSea überein. Fragen Sie nach dem korrekten Slug oder der URL. |
| Ratenbegrenzungsmeldung (mit einer Verzögerung in Sekunden) | Warten Sie die angegebene Zeit, bevor Sie es erneut versuchen, und informieren Sie den Benutzer. |
| "Payment refused by safety policy" | Der Server hat die Zahlungsbedingungen vor dem Signieren abgelehnt. Melden Sie es; versuchen Sie nicht, es zu umgehen. |
| "Payment was not accepted" | Die API hat die Zahlung nicht akzeptiert. Melden Sie es; wiederholen Sie es nicht selbstständig. |
| "paid request limit ... reached" | Das Sitzungsausgabenlimit wurde erreicht. Der Benutzer muss den Client neu starten oder NFTDATA_MAX_REQUESTS erhöhen. |
| Timeout | Eine Zahlung wurde möglicherweise autorisiert und nicht wiederholt. Informieren Sie den Benutzer; bieten Sie an, es nur erneut zu versuchen, wenn er zustimmt. |
| Allgemeine "The request failed."-Meldung | Melden Sie es als Fehler. Raten Sie nicht über die Ursache. |
Beispielaufforderungen
- "Verwende den NFT Data MCP-Server. Was ist der Floor-Preis der
azuki-Kollektion?" - "Hole die Marktstatistiken für
basedpunks: Floor-Preis, Verkäufe und Volumen der letzten 24h, 7d und 30d, Angebot und Besitzer."" - "Welche Vertragsadresse und Kette verwendet
miladyauf OpenSea?" - "Vergleiche
azukiundbasedpunksnach Floor-Preis und 30-Tage-Volumen. Vergleiche nur Zahlen, die dieselbe Währung verwenden."" - "Hier ist der OpenSea-Link: https://opensea.io/collection/azuki. Fasse die Kollektion als kurzen Bericht zusammen.""
- "Zeige die rohe JSON-Antwort für
azukiund erkläre jedes Feld."" - "Wie viele Besitzer hat
azukiim Vergleich zu seinem Gesamtangebot?" (ein abgeleitetes Verhältnis, also kennzeichne es als abgeleitet)
Zahlungsdetails
- Preis: $0,002 USDC pro erfolgreichem, nicht zwischengespeichertem Aufruf.
- Netzwerk: Nur Base Mainnet (
eip155:8453), bezahlt in USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913). Das Zahlungsnetzwerk ist Base Mainnet, unabhängig davon, auf welcher Blockchain die abgefragte Kollektion ist. Die Abfrage einer Kollektion auf einer anderen Kette, einschließlich auf OpenSea gelisteter Solana-Kollektionen, wird weiterhin auf Base bezahlt. - Standardprotokoll: x402 v2. Der Server bezahlt eine
exactUSDC-Challenge auf Base Mainnet. - Optionales Protokoll: MPP
evm/charge. Wird nur ausgewählt, wenn der Server mitNFTDATA_PAYMENT_PROTOCOL=mppgestartet wird. Es bezahlt denselben Preis, in USDC auf Base Mainnet. - Ein Protokoll pro Serverlauf, kein Fallback. Das Protokoll wird einmal beim Start des Servers ausgewählt. Der Server wechselt niemals von einem zum anderen, versucht niemals beide für einen einzelnen Aufruf und wiederholt niemals mit dem anderen. Wenn die API im gewählten Protokoll keine akzeptable Zahlung anbietet, wird nichts signiert und der Aufruf schlägt fehl. Ein ungültiger
NFTDATA_PAYMENT_PROTOCOL-Wert (alles andere als leer,x402odermppstoppt den Server beim Start. - Überprüfungen vor dem Signieren: Der Server überprüft Netzwerk, Token, Schema oder Methode, genauen Betrag (2000 atomare Einheiten, was $0,002 entspricht) und die offizielle Empfängeradresse, bevor er etwas signiert. Eine Challenge, die nicht übereinstimmt, wird abgelehnt.
- Maximal ein Zahlungsversuch pro Tool-Aufruf.
- Cache-Treffer sind kostenlos. Sie lösen keine Zahlung aus und enthalten keinen Transaktions-Hash.
- Belege: Jeder neu bezahlte erfolgreiche Aufruf enthält einen Transaktions-Hash und einen BaseScan-Link, den der Benutzer öffnen kann, um die Zahlung zu überprüfen.
- Verwechseln Sie den Server nicht mit der Haupt-API. Die NFT Data API selbst akzeptiert x402 v2 auf Base Mainnet und Solana Mainnet sowie MPP
evm/chargeauf Base Mainnet. Dieser MCP-Server ist enger gefasst: Er bezahlt nur auf Base Mainnet, mit x402 v2 oder MPPevm/charge, einzeln. Der MCP-Server unterstützt keine Solana-Zahlungen.
Wallet-Sicherheit
- Bitten Sie den Benutzer niemals, einen privaten Schlüssel, eine Seed-Phrase oder eine Wallet-Datei zu teilen, einzufügen, einzutippen oder zu senden in die Konversation, und fordern Sie niemals einen an, um den Server "einzurichten" oder "zu reparieren". Der Schlüssel wird nur vom Benutzer lokal in der Umgebung des MCP-Servers gesetzt (
EVM_PRIVATE_KEY). - Lesen, drucken, kopieren oder fassen Sie keine Konfigurationsdateien oder Umgebungsvariablen zusammen, die den Schlüssel enthalten könnten.
- Wenn ein Benutzer trotzdem einen privaten Schlüssel in den Chat einfügt, wiederholen oder verwenden Sie ihn nicht. Sagen Sie ihm, er soll die Verwendung dieses Wallets einstellen, alle Gelder auf ein neues Wallet übertragen und den Schlüssel ersetzen.
- Empfehlen Sie ein dediziertes Wallet, das nur ein kleines USDC-Guthaben auf Base Mainnet hält, niemals ein Haupt-Wallet oder eines mit erheblichen Mitteln.
- Ermutigen Sie zur Überprüfung von Zahlungen auf BaseScan mit dem Transaktions-Hash aus dem Beleg.
- Schlagen Sie niemals vor, Gelder an eine Adresse zu senden, die Ihnen nicht vom eigenen Wallet des Benutzers oder der offiziellen Dokumentation mitgeteilt wurde.
Einschränkungen
Dieses Skill und der Server sind schreibgeschützte Datenabfragen für Kollektionen. Sie sind nicht:
- ein allgemeines NFT-Such- oder Entdeckungstool: keine Suche nach Namen, Merkmalen, Seltenheit, Preisspanne oder Rangliste und keine Listen mit "Top"- oder "Trending"-Kollektionen
- ein Token-Ebene-Tool: keine Abfrage einzelner NFTs, Token-IDs, Metadaten, Seltenheit oder Besitzverhältnisse
- ein Wallet-Tool: keine Wallet-Guthaben, Bestände, Portfolios oder Transaktionsverläufe
- ein Handels- oder Transaktionswerkzeug: es kann nichts kaufen, verkaufen, listen, bieten, minten, übertragen, brücken oder tauschen, und es bewegt keine Gelder, außer der kleinen Zahlung pro Aufruf
- ein historischer oder Echtzeit-Feed: es gibt eine Momentaufnahme pro Aufruf zurück, ohne Preishistorie oder Streaming-Updates
- ein Preis-Orakel oder Berater: keine Währungsumrechnung, Bewertung, Vorhersagen oder Anlageberatung
Weitere Grenzen:
- Es können nur Kollektionen abgefragt werden, die auf OpenSea existieren, und die Eingabe muss der OpenSea-Slug sein.
- Einige Felder können bei manchen Kollektionen fehlen oder
nullsein. - Die Daten stammen von OpenSea und werden gemeldet...