mcp-tenderly

Ein MCP-Server, der einer KI-Assistentin die Möglichkeit gibt, EVM-Transaktionen zu simulieren und zu debuggen, warum sie reverten, unter Verwendung der kostenlosen Simulations-API von Tenderly.

Frag „Würde diese Transaktion funktionieren?" oder „Warum ist das fehlgeschlagen?" und erhalte eine Antwort, die auf echtem Fork-Chain-State basiert — den dekodierten Call-Trace, den Revert-Grund, die exakte Quellcode-Zeile — statt einer Vermutung.

Es wird nie etwas gesendet. Simulationen sind schreibgeschützt gegen einen Fork, daher können sie bedenkenlos ausgeführt werden.

Warum es das gibt

Eine Assistentin, die über eine On-Chain-Transaktion nachdenkt, arbeitet normalerweise blind: Sie kann den Vertragsquellcode lesen, aber sie kann dir nicht sagen, ob ein Call gegen den aktuellen State revertet, was das Gas tatsächlich kostet, oder welcher von acht verschachtelten Delegatecalls der fehlgeschlagene ist. Tenderly kann alle drei beantworten, und seine Simulations-API ist mit einem kostenlosen Konto nutzbar.

Der schwierige Teil ist nicht der API-Aufruf — es ist die Tatsache, dass eine simulation_type: "full"-Antwort für eine echte DeFi-Transaktion häufig über ein Megabyte JSON umfasst: einen State-Diff über jeden berührten Storage-Slot, einen Call-Tree mit hunderten von Frames Tiefe. Das einem Modell zu übergeben ist sowohl unbezahlbar als auch nutzlos, weil die Antwort auf „Warum hat das revertet?" vier Zeilen tief darin vergraben ist.

Die eigentliche Arbeit dieses Servers ist also der Formatierer: Er stellt das Ergebnis an den Anfang, dann den Revert-Grund und den source-gemappten Frame, dann dekodierte Events, dann den Call-Tree als eingerücktes ASCII-Diagramm — und er gibt immer an, wenn er etwas abgeschnitten hat, denn eine stille Obergrenze liest sich wie „das war alles".

Related MCP server: evmscope

Schnellstart

Erfordert Node.js 22.12 oder neuer.

1. Tenderly-Zugangsdaten besorgen

Alle drei stammen aus einem kostenlosen Tenderly-Konto:

Beide Slugs sind die URL-Slugs, nicht die Anzeigenamen — ein Projekt, das als „My Project" angezeigt wird, ist normalerweise my-project. Der Server validiert das beim Start und sagt dir, welche Variable falsch ist, statt es später als 404 auftauchen zu lassen.

2. Den Server bei deinem Client registrieren

Claude Code

claude mcp add tenderly \
  -e TENDERLY_API_KEY=your-token \
  -e TENDERLY_ACCOUNT_SLUG=your-account \
  -e TENDERLY_PROJECT_SLUG=your-project \
  -- npx -y mcp-tenderly

Claude Desktop, Cursor oder ein anderer MCP-Host — füge Folgendes zur MCP-Konfigurationsdatei des Clients hinzu:

{
  "mcpServers": {
    "tenderly": {
      "command": "npx",
      "args": ["-y", "mcp-tenderly"],
      "env": {
        "TENDERLY_API_KEY": "your-token",
        "TENDERLY_ACCOUNT_SLUG": "your-account",
        "TENDERLY_PROJECT_SLUG": "your-project"
      }
    }
  }
}

Aus einem lokalen Klon ausführen

git clone https://github.com/py-zoid/mcp-tenderly.git
cd mcp-tenderly
npm install
npm run build

Danach den Client auf das Build-Ergebnis verweisen und <repo> durch den absoluten Pfad zu deinem Klon ersetzen:

{
  "mcpServers": {
    "tenderly": {
      "command": "node",
      "args": ["<repo>/dist/index.js"],
      "env": { "TENDERLY_API_KEY": "…", "TENDERLY_ACCOUNT_SLUG": "…", "TENDERLY_PROJECT_SLUG": "…" }
    }
  }
}

Tools

tenderly_simulate_transaction

Simuliert eine Transaktion gegen den geforkten Chain-State. Gibt Erfolg oder Revert zurück, verbrauchtes Gas, den Revert-Grund mit einem source-gemappten Stack-Trace, sofern der Vertrag verifiziert ist, dekodierte Events, Token-Transfers und den dekodierten Call-Trace.

Akzeptiert network als Namen (base, arbitrum, polygon, sepolia, …) oder als numerische Chain-ID, die üblichen Transaktionsfelder (from, to, data, value, gas, gas_price), eine optionale block_number als Fork-Basis und state_overrides, um Balances, Nonces, Storage-Slots oder Bytecode zu fälschen.

tenderly_simulate_bundle

Simuliert bis zu 20 Transaktionen in Reihenfolge gegen gemeinsamen State, sodass jede die Auswirkungen der vorherigen sieht. Das ist das Tool für Abläufe, die nicht eine Transaktion nach der anderen geprüft werden können — Approve dann Swap, Deploy dann Initialisierung, oder das Nachspielen einer Exploit-Sequenz. Es berichtet, welcher Schritt in der Sequenz fehlgeschlagen ist.

tenderly_get_simulation

Ruft eine gespeicherte Simulation anhand ihrer ID ab und rendert ihr Ergebnis und den vollständigen Call-Trace. Verwende es, um einen abgeschnittenen Trace tiefer zu untersuchen, den standardmäßig weggelassenen State-Diff abzurufen oder eine früher erstellte oder aus der Tenderly-UI stammende Simulation zu inspizieren.

Eine Sache, die du wissen solltest, weil sie das Verhalten dieses Tools prägt: Der gespeicherte Simulationsdatensatz von Tenderly enthält nur Metadaten — Eingaben, Gas, Status, Fehlermeldung. Der Call-Trace wird nicht aufbewahrt. Der Trace wird also durch erneutes Abspielen der aufgezeichneten Eingaben auf dem aufgezeichneten Block reproduziert, was originalgetreu ist (gleicher Fork, gleiches Ergebnis), aber eine Simulation gegen dein Rate-Limit kostet. Das Replay wird nicht gespeichert, verbraucht also kein Speicherkontingent für Simulationen. Übergib reconstruct_trace: false für eine günstige Metadaten-Abfrage.

tenderly_list_simulations

Listet kürzlich gespeicherte Simulationen im Projekt auf, eine Zeile pro Simulation, um eine ID zu finden.

Ausgabegröße steuern

Jedes Read-Tool akzeptiert dieselben Ausgabesteuerungen. Die Standardwerte sind so eingestellt, dass eine typische Antwort erschwinglich bleibt:

Ein vollständiger Tenderly-Trace verschränkt Storage- und Log-Opcodes mit echten Calls — eine einfache USDC-Überweisung ergibt ein Dutzend SLOADs um vier echte Calls herum, und eine DeFi-Transaktion Hunderte. Wenn sie drin bleiben, verbrauchen sie das Frame-Budget und drängen die Calls, die einen Revert erklären, aus der Ausgabe heraus. Deshalb sind sie standardmäßig ausgeblendet, und die Anzahl wird gemeldet. Interne Solidity-Funktionsframes (JUMPDEST) bleiben erhalten: Sie ermöglichen es, einen Revert durch eine Bibliothek oder einen Proxy zu verfolgen.

Hinweise zum kostenlosen Tarif

Dieser Server verwendet bewusst nur die v1-Simulations-REST-Endpunkte, die im kostenlosen Plan funktionieren: /simulate, /simulate-bundle, /simulations und /simulations/{id}. Er berührt niemals das Web3-Gateway, DevNets, Virtual TestNets, Alerts oder die Actions-API — diese sind kostenpflichtig oder OAuth-geschützt, und sie zu verwenden würde den Server für genau die Nutzer, die er anspricht, verwirrend scheitern lassen.

Zwei Dinge zum Kontingent:

• Gespeicherte Simulationen verbrauchen Kontingent. Standardmäßig werden Simulationen gespeichert, weil eine Dashboard-URL beim Debuggen sehr viel wert ist. Setze TENDERLY_SAVE_SIMULATIONS=false oder übergib save: false pro Aufruf, um sie flüchtig zu halten.

• Rate-Limits erzeugen eine 429. Der Client wiederholt diese mit Backoff, respektiert Retry-After und meldet das Limit dann klar, statt zu hängen.

Optionale Konfiguration

Sicherheits- und Vertrauensmodell

Simulationen senden nie etwas. Jeder Aufruf ist schreibgeschützt gegen einen Tenderly-Fork. Es wird keine Transaktion signiert oder gesendet, und der Server hält keine Schlüssel außer deinem Tenderly-Zugriffstoken.

Ein ausgehender Host. Der Server kommuniziert nur mit api.tenderly.co. Nichts anderes wird kontaktiert, und es werden keine Telemetriedaten erfasst.

Dein Zugriffstoken bleibt außerhalb der Ausgabe. Es wird nur als X-Access-Key-Header gesendet, wird auf keiner Log-Ebene protokolliert und ist aus Fehlermeldungen und Pfaden ausgeschlossen. Ein Test stellt sicher, dass es weder in stdout noch in stderr vorkommt.

Simulationsausgabe wird als unvertrauenswürdige Eingabe behandelt. Das ist der Punkt, den es zu verstehen lohnt, weil man ihn leicht übersieht. Vertragsnamen, Token-Symbole, Funktionsnamen, dekodierte Strings, verifizierte Quellcode-Zeilen und Revert-Gründe werden alle von demjenigen kontrolliert, der den Vertrag bereitgestellt hat — und der Sinn dieses Servers ist es, ihn auf Verträge zu richten, denen du noch nicht vertraust. Ein Vertrag kann mit beliebigem Text revert()en, der an der prominentesten Stelle der Ausgabe landet.

Deshalb wird all dieser Text vor dem Rendern durch einen Sanitizer geschickt: Leerzeichen werden auf eine einzelne Zeile reduziert, Zero-Width- und Bidi-Override-Zeichen werden entfernt, und die Länge wird mit angegebener Kürzung begrenzt. Das verhindert, dass feindliche Chain-Daten eine Markdown-Überschrift, ein Listenelement oder irgendetwas anderes fälschen, das einem Modell wie Anweisungen statt wie Daten erscheinen könnte. Es ist eine strukturelle Verteidigung, kein Versuch, böswillige Absicht zu erkennen — unvertrauenswürdiger Text kann das Feld, zu dem er gehört, schlicht nicht verlassen. Gewöhnliche Revert-Strings sind davon nicht betroffen.

Das macht die Ausgabe eines feindlichen Vertrags nicht wahr, sondern nur inert. Behandle ein Simulationsergebnis als einen Bericht über unvertrauenswürdigen Code, was es auch ist.

Fehlerbehebung

Der Server beendet sich sofort mit einer Konfigurationsmeldung. Das ist beabsichtigt — er weigert sich zu starten, statt innerhalb deines ersten Tool-Aufrufs zu scheitern. Die Meldung nennt die fehlerhafte Variable. Der Exit-Code ist 78 (EX_CONFIG).

401 oder 403. Das Token muss ein Access Token aus den Account-Einstellungen sein, kein Projekt-Secret und kein RPC-Key, und es muss zu einem Konto mit Zugriff auf TENDERLY_ACCOUNT_SLUG gehören.

404. Fast immer ein Slug-Problem: Anzeigename statt Slug, oder account/project in eine einzelne Variable eingefügt.

Kein Revert-Grund bei einem Fehler. Der Vertrag ist wahrscheinlich nicht verifiziert oder verwendet einen Custom Error. Der Call-Trace identifiziert trotzdem den fehlgeschlagenen Frame, und der Selektor wird angezeigt, damit du ihn nachschlagen kannst.

Alles sieht leer aus. Führe erneut mit include_raw_response: true aus, um zu sehen, was Tenderly tatsächlich zurückgegeben hat.

Server-Logs gehen als JSON nach stderr — prüfe die Server-Log-Ansicht deines MCP-Clients. Der API-Key wird nie protokolliert.

Entwicklung

npm install        # also installs the git hooks via core.hooksPath
npm run verify     # everything CI runs: format, lint, types, unit, stdio smoke
npm test           # unit tests only
npm run test:smoke # builds, then drives dist/index.js over real stdio

npm run verify ist exakt das, was CI ausführt — das Workflow-YAML ruft nur .github/scripts/verify.sh auf, es gibt also nichts, was du nicht lokal reproduzieren kannst.

Siehe CLAUDE.md für die Architektur und die Design-Entscheidungen, die du kennen solltest, bevor du etwas änderst.

Lizenz

MIT