Arbitrum MCP Server

Instructions

Implementation Reference

• src/index.ts:504-521 (handler)

  MCP tool handler in the CallToolRequestSchema switch statement. Instantiates NitroNodeClient with resolved RPC URL and calls its replayBlockTransactions method with provided arguments, returning JSON-stringified result.

  case "arbtrace_replayBlockTransactions": {
    const rpcUrl = await this.resolveRpcUrl(
      (args.rpcUrl as string) || (args.chainName as string)
    );
    const nodeClient = new NitroNodeClient(rpcUrl);
    const result = await nodeClient.replayBlockTransactions(
      args.blockNumOrHash as string,
      (args.traceTypes as string[]) || ["trace"]
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:1236-1265 (schema)

  Tool schema definition including name, description, and inputSchema for validation. Part of the tools array returned by getAvailableTools() for tool registration/discovery.

    name: "arbtrace_replayBlockTransactions",
    description:
      "Replay and trace all transactions in a specific block (requires trace API)",
    inputSchema: {
      type: "object" as const,
      properties: {
        rpcUrl: {
          type: "string",
          description:
            "The RPC URL of the Arbitrum node (optional if default is set)",
        },
        chainName: {
          type: "string",
          description:
            "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL",
        },
        blockNumOrHash: {
          type: "string",
          description: "Block number or hash to replay",
        },
        traceTypes: {
          type: "array",
          description:
            "Array of trace types (e.g., ['trace', 'stateDiff'])",
          items: { type: "string" },
        },
      },
      required: ["blockNumOrHash"],
    },
  },

• src/clients/nitro-node-client.ts:257-275 (helper)

  Supporting method in NitroNodeClient that performs the actual RPC call to 'arbtrace_replayBlockTransactions' on the node, handles errors, and returns TraceResult.

  async replayBlockTransactions(
    blockNumOrHash: string,
    traceTypes: string[]
  ): Promise<TraceResult> {
    try {
      const traces = await this.makeRpcCall(
        "arbtrace_replayBlockTransactions",
        [blockNumOrHash, traceTypes]
      );
      return { traces };
    } catch (error) {
      return {
        traces: null,
        error: `Trace replayBlockTransactions not supported on this RPC endpoint: ${
          (error as Error).message
        }`,
      };
    }
  }