mcp-tenderly

MCPサーバーです。AIアシスタントにEVMトランザクションのシミュレーションと、なぜリバートしたのかのデバッグを可能にするもので、Tenderlyの無料枠のシミュレーションAPIを使用します。

「このトランザクションは成功するか？」または「なぜ失敗したのか？」と問いかけると、実際のフォーク済みチェーン状態に基づく回答を得られます。推測ではなく、デコードされたコールトレース、リバート理由、正確なソース行が返ってきます。

何かがブロードされることはありません。シミュレーションはフォークに対する読み取り専用の操作なので、自由に実行しても安全です。

なぜこれが存在するのか

オンチェーンのトランザクションについて推論するアシスタントは、通常は暗闇で作業しています。コントラクトのソースは読めても、現在の状態に対する呼び出しがリバートするかどうか、実際のガスがいくらかかるのか、8つにネストしたdelegatecallのうちどれが失敗したのかを伝えることはできません。Tenderはその3つすべてに答えることができ、そのシミュレーションAPIは無料アカウントで利用できます。

難しいのはAPIを呼び出すことではありません。実際のDeFiトランザクションを指すとき、simulation_type: "full"レスポンスはしばしば1メガバイト超のJSONになります。触れるすべてのストレージスロットのstate diff、数百フレームの深さのコールツリー。それをモデルに渡すのは高すぎるし、役に立ちません。なぜなら「なぜリバートしたのか」の答えは、その中に埋もれた4行だからです。

そこで、このサーバーの本当の仕事はフォーマッタです。つまり、結果を先頭に置き、次にリバート理由とソースマップ済みのフレーム、その次にデコード済みイベント、そしてコールツリーをインデント付きASCIIダイアグラムとして出力し、何かを切り詰めたときは必ずその旨を明示します。黙って上限で切ると、「それが全てだ」と読まれるからです。

Related MCP server: evmscope

クイックスタート

Node.js 22.12以降が必要です。

1. Tenderlyの認証情報を取得する

3つとも、Tenderlyの無料アカウントで入手できます。

どちらのスラッグもURLスラッグであり、表示名ではありません。「My Project」として表示されるプロジェクトは、通常my-projectです。サーバーは起動時にこれを検査し、後で404として出現させるのではなく、どの変数が間違っているかを示します。

2. サーバーをクライアントに登録する

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、その他のMCPホスト — クライアントのMCP設定ファイルに追加します。

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

ローカルクローンから実行する

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

次に、<repo>をクローンの絶対パスに置き換えて、クライアントをビルド出力に接続します:

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

ツール

tenderly_simulate_transaction

フォークされたチェーン状態に対して、1つのトランザクションをシミュレートします。成功かリバートか、使用量されたガス、検証済みコントラクトの場合のリバート理由（ソースマップ済みスタックトレース付き）、デコード済みイベント、トークン転送、デコード済みコールトレースを返します。

networkは名前（base、arbitrum、polygon、sepoliaなど）または数値のチェーンIDで受け付けます。通常のトランザクションフィールド（from、to、data、value、gas、gas_price）、フォーク元を指定するオプションのblock_number、残高・nonce・ストレージスロット・バイトコードを偽装するためのstate_overridesも受け付けます。

tenderly_simulate_bundle

最大20件のトランザクションを共有状態に対して順番にシミュレートし、それぞれが前のトランザクションの効果を見ることができます。1件ずつでは確認できないフローに対応するツールです。承認してからスワップ、デプロイしてから初期化、エクスプロイトの一連の再現まで。どのステップで壊れたかを報告します。

tenderly_get_simulation

保存済みのシミュレーションをIDで検索し、その結果と完全なコールトレースを表示します。切り詰められたトレースをより深く調べる、デフォルトでは省略されるstate diffを取得する、または以前作成したシミュレーションやTenderlyのUIから作成したシミュレーションを調べるために使います。

このツールの動きを左右する重要な点を一つ: Tenderlyの保存されたシミュレーションレコードにはメタデータのみが保存されます——入力、ガス、ステータス、エラーメッセージです。コールトレースは保持されません。そのためトレースは、記録された入力と記録されたブロックに対して再生されることで再構築されます。これは忠実ですが（同じフォーク、同じ結果）、レート制限に対して1回のシミュレーションを消費します。再生は保存されないため、保存シミュレーションのクォータは消費しません。reconstruct_trace: falseを渡すと、安価なメタデータのみの検索になります。

tenderly_list_simulations

プロジェクト内の最近の保存済みシミュレーションを1行ずつ一覧表示し、IDを見つけます。

出力サイズの制御

すべての読み取りツールは同じ出力制御を取ります。デフォルトは、典型的なレスポンスを手頃なサイズに保つように調整されています:

Tenderlyの完全なトレースは、ストレージとログのオペコードを実際の呼び出しとインターリーブします。単純なUSDC送金でも、実際の呼び出し4つを取り囲むSLOADが十数個発生し、DeFiトランザクションなら数百個になります。そのため、デフォルトでは非表示にされ、その数が報告されます。Solidity内部の関数フレーム（JUMPDEST）は保持されます。これらは、ライブラリやプロキシを介してリバートを追跡するために使用できます。

無料枠に関する注記

このサーバーが意図的に使用するのは、無料プランで動作するv1のシミュレーションRESTエンドポイントのみです: /simulate、/simulate-bundle、/simulations、そして/simulations/{id}です。Web3 Gateway、DevNets、Virtual TestNets、Alerts、Actions APIには一切触れません。これらは有料またはOAuthで閉じており、それらに手を出すと、ターゲットとする利用者に対してサーバーが紛らわしく失敗してしまうからです。

クォータについて2つの点を知っておくべきです:

• 保存されたシミュレーションはクォータを消費します。 デフォルトではダッシュボードのURLがデバッグに非常に価値があるため、シミュレーションは保存されます。TENDERLY_SAVE_SIMULATIONS=falseを設定するか、呼び出しごとにsave: falseを渡すと、一時的にできます。

• レート制限は429になります。 クライアントはバックオフでリトライし、Retry-Afterを尊重して、それから制限を明確に報告します。ハングしません。

オプション設定

セキュリティと信頼モデル

シミュレーションは決してブロードキャストされません。 すべての呼び出しは、Tenderlyフォークに対する読み取り専用です。トランザクションが署名付きや送信されることはなく、サーバーが保持するキーはTenderlyのアクセストークンのみです。

送信先ホストは1つのみです。 サーバーが通信するのはapi.tenderly.coだけです。他のどこにも接続せず、テレメトリーも収集されません。

アクセストークンは出力には現れません。 X-Access-Keyヘッダーのみで送信され、あらゆるログレベルで、またエラーメッセージやパスからも除外されます。テストがstdoutとstderrの両方から出力されないことを確認しています。

シミュレーション出力は、信頼されていない入力として扱われます。 これは理解する価値のあるもので、見逃しやすいからです。コントラクト名、トークンシンボル、関数名、デコードされた文字列、検証済みソースの行、リバー理由はすべて、コントラクトをデプロイした人の制御下にあります。このサーバーのポイントは、まだ信用しないコントラクトにそれを向けることです。コントラクトは好きな文字列でrevert()でき、その文字列が出力の最も目立つ位置に入ります。

そのため、レンダリングの前にそのようなテキストはサニタイザーを通されます。空白は単一の行にまとめられ、ゼロ幅のものは除去され、長さは制限され、その切り詰めが明示されます。これにより、敵対的なチェーンデータがMarkdownの見出しやリスト項目などを偽造することを防ぎます。モデルへの「指示」ではなくデータであるべきものを「指示」と読ませる可能性のあるものを防ぎます。これは「構造的な防御」であり、悪意を検出する試みではありませんが、信頼されていないテキストが属するフィールドを逃れることはできません。通常のリバー文字列は影響を受けません。

これは、敵対的なコントラクトの出力を真実にするものではなく、不活性にするだけです。シミュレーションの結果を、信頼できないコードに関するレポートとして扱ってください。それが実態です。

トラブルシューティング

サーバーが起動直後に設定プロンプトと終了する。 これは設計上の動作です。最初のツール呼び出し内で失敗させるのではなく、起動を拒否します。メッセージは問題の変数を明示します。終了コードは78（EX_CONFIG）です。

401または403 トークンは、Account Settings のAccess Tokenである必要があります。プロジェクトシークキーやRPCキーではありません。また、TENDERLY_ACCOUNT_SLUGにアクセス権を持つアカウントに属している必要があります。

404。 ほとんどがスラッグに関する問題です。表示名がスラッグになっているか、account/projectが1つの変数に貼り付けられています。

失敗時にリバー理由が表示されない。 コントリが未検証であるか、カスタムエラーメッセージが使用された可能性があります。コールトレースは失敗したフレームを識別し、セレクタも表示されるので、それを調べられるます。

すべてが空に見える。 include_raw_response: trueを付けて再実行すると、Tenderyが実際に返した内容が見えます。

サーバーログはJSONとしてstderrに出力されます。MCPクライアントのサーバーログビューを確認してください。APIキーがログに記録されることはありません。

開発

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はCIが実行するものとまったく同じです。ワークフローYAMLは.github/scripts/verify.shのみを呼び出すので、ローカルで再現できないことはありません。

アーキテクチャと、変更する前に知っておくべき設計上の判断についてはCLAUDE.mdを参照してください。

ライセンス

MIT