mcp-tenderly

一个 MCP 服务器，让 AI 助手能够使用 Tenderly 的免费模拟 API 模拟 EVM 交易并调试其回滚原因。

询问“这笔交易能成功吗？”或“为什么失败了？”，即可获得基于真实分叉链状态的答案——解码后的调用轨迹、回滚原因、精确的源代码行——而不是猜测。

任何内容都不会被广播。模拟是针对分叉的只读操作，因此可以放心自由运行。

为什么存在

一个推理链上交易的助手通常是盲目的：它可以读取合约源代码，但无法告诉你调用是否会针对当前状态回滚、实际 gas 成本是多少，或者八个嵌套 delegatecall 中哪一个是失败的。Tenderly 可以回答这三个问题，而且其模拟 API 在免费账户上即可使用。

难点不在于调用 API——而在于，对于真实的 DeFi 交易，simulation_type: "full" 的响应经常超过一兆字节的 JSON：包含每个触及的存储槽的状态差异、深度达数百帧的调用树。将其交给模型既负担不起也无用，因为“为什么回滚”的答案只是其中埋藏的四行。

因此，这个服务器真正的工作在于格式化器：它先呈现结果，然后是回滚原因和源映射帧，接着是解码后的事件，再是以缩进 ASCII 图形式呈现的调用树——并且它总是说明何时截断了内容，因为静默的上限会被误读为“这就是全部”。

Related MCP server: evmscope

快速开始

需要 Node.js 22.12 或更高版本。

1. 获取 Tenderly 凭据

这三项都来自免费的 Tenderly 账户：

两个 slug 都是 URL slug，而不是显示名称——显示为“我的项目”的项目通常是 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

针对分叉链状态模拟一笔交易。返回成功或回滚、使用的 gas、回滚原因（如果合约已验证，则带有源映射的堆栈跟踪）、解码后的事件、代币转移以及解码后的调用轨迹。

接受 network 作为名称（base、arbitrum、polygon、sepolia 等）或数字链 ID，常规交易字段（from、to、data、value、gas、gas_price），可选的 block_number 用于分叉，以及 state_overrides 用于伪造余额、nonce、存储槽或字节码。

tenderly_simulate_bundle

按顺序模拟最多 20 笔交易，共享状态，因此每笔交易都能看到之前交易的效果。这是用于无法逐笔检查的流程的工具——先批准再交换、先部署再初始化，或重放漏洞利用序列。它会报告序列中哪一步失败了。

tenderly_get_simulation

按 ID 查找已保存的模拟，并渲染其结果和完整调用轨迹。用于深入查看被截断的轨迹、获取默认省略的状态差异，或检查之前创建或从 Tenderly UI 创建的模拟。

有一点值得了解，因为它塑造了此工具的行为：Tenderly 的已保存模拟记录仅存储元数据——输入、gas、状态、错误消息。调用轨迹不会被保留。因此，轨迹是通过在记录的区块重放记录的输入来重现的，这是忠实的（相同的分叉，相同的结果），但会消耗一次模拟配额。重放不会被保存，因此不会消耗已保存模拟的配额。传递 reconstruct_trace: false 以进行廉价的仅元数据查找。

tenderly_list_simulations

列出项目中最近的已保存模拟，每行一个，以查找 ID。

控制输出大小

每个读取工具都接受相同的输出控制。默认值经过调整，以保持典型响应可负担：

完整的 Tenderly 轨迹将存储和日志操作码与真实调用交织在一起——一次普通的 USDC 转账会在四个实际调用周围产生十几个 SLOAD，而 DeFi 交易会产生数百个。如果保留它们，会消耗帧预算，并将解释回滚的调用挤出输出，因此默认隐藏它们并报告计数。内部 Solidity 函数帧（JUMPDEST）会被保留：这些帧让你能够通过库或代理跟踪回滚。

免费套餐说明

此服务器特意仅使用免费计划上可用的 v1 模拟 REST 端点：/simulate、/simulate-bundle、/simulations 和 /simulations/{id}。它从不接触 Web3 Gateway、DevNets、Virtual TestNets、Alerts 或 Actions API——这些是付费或 OAuth 门控的，使用它们会使服务器对其目标用户产生令人困惑的失败。

关于配额有两件事需要了解：

• 已保存的模拟消耗配额。 默认情况下模拟会被保存，因为调试时仪表板 URL 非常有价值。设置 TENDERLY_SAVE_SIMULATIONS=false，或每次调用传递 save: false，以保持其临时性。

• 速率限制会产生 429。 客户端会以退避方式重试这些请求，遵循 Retry-After，然后明确报告限制，而不是挂起。

可选配置

安全与信任模型

模拟永远不会广播。 每次调用都是针对 Tenderly 分叉的只读操作。不会签署或发送任何交易，服务器除了你的 Tenderly 访问令牌外不持有任何密钥。

一个出站主机。 服务器只与 api.tenderly.co 通信。不会联系其他任何内容，也不会收集遥测数据。

你的访问令牌不会出现在输出中。 它仅作为 X-Access-Key 标头发送，在任何日志级别都不会被记录，并且被排除在错误消息和路径之外。测试断言它不会出现在 stdout 和 stderr 中。

模拟输出被视为不可信输入。 这是值得理解的一点，因为它很容易被忽略。合约名称、代币符号、函数名称、解码后的字符串、已验证的源代码行和回滚原因都由部署合约的人控制——而这个服务器的目的就是将其指向你尚未信任的合约。合约可以用它喜欢的任何字符串 revert()，这会出现在输出中最显眼的位置。

因此，所有此类文本在渲染前都会经过净化器处理：空白被折叠为单行，零宽度和双向覆盖字符被移除，长度被截断并说明截断情况。这可以防止敌意链数据伪造 markdown 标题、列表项或任何其他可能被模型解读为指令而非数据的内容。这是一种结构性防御，而不是试图检测恶意意图——不可信文本根本无法逃出其所属字段。普通的回滚字符串不受影响。

这并不会使敌意合约的输出变得真实，只会使其惰性。将模拟结果视为关于不可信代码的报告，事实就是如此。

故障排除

服务器立即退出并显示配置消息。 这是设计使然——它拒绝启动，而不是在第一次工具调用中失败。消息会指出有问题的变量。退出代码为 78（EX_CONFIG）。

401 或 403。 令牌必须是账户设置中的访问令牌，而不是项目密钥或 RPC 密钥，并且必须属于有权访问 TENDERLY_ACCOUNT_SLUG 的账户。

404。 几乎总是 slug 问题：显示名称而不是 slug，或者将 account/project 粘贴到一个变量中。

失败时没有回滚原因。 合约可能未验证，或者使用了自定义错误。调用轨迹仍然会识别失败的帧，并显示选择器以便你查找。

一切看起来都是空的。 使用 include_raw_response: true 重新运行，以查看 Tenderly 实际返回的内容。

服务器日志以 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