Arbitrum MCP Server

Instructions

Implementation Reference

• src/index.ts:684-700 (handler)

  MCP tool handler implementation. Resolves RPC URL from chainName or rpcUrl, creates NitroNodeClient, calls sendExpressLaneTransaction with the submission argument, and returns the JSON-stringified result.
  case "timeboost_sendExpressLaneTransaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.sendExpressLaneTransaction( args.submission ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; }
• src/index.ts:1506-1529 (schema)

  Tool schema definition including inputSchema with properties for rpcUrl, chainName, and required submission object. Used in listTools response.
  name: "timeboost_sendExpressLaneTransaction", description: "Submit priority transactions through express lanes for faster processing (requires timeboost 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", }, submission: { type: "object", description: "Express lane submission data", }, }, required: ["submission"], }, },
• src/index.ts:93-821 (registration)

  Registration of the listTools handler which returns all available tools including timeboost_sendExpressLaneTransaction via getAvailableTools().
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { try { console.error("Handling list tools request"); return { tools: this.getAvailableTools(), }; } catch (error) { console.error("Error in list tools handler:", error); throw error; } }); this.server.setRequestHandler(CallToolRequestSchema, async (request) => { try { console.error("Handling call tool request:", request.params.name); const { name, arguments: args } = request.params; if (!args) { throw new Error("Missing arguments"); } switch (name) { case "set_rpc_url": this.defaultRpcUrl = args.rpcUrl as string; return { content: [ { type: "text", text: `Default RPC URL set to: ${this.defaultRpcUrl}`, }, ], }; case "get_rpc_url": return { content: [ { type: "text", text: this.defaultRpcUrl ? `Current default RPC URL: ${this.defaultRpcUrl}` : "No default RPC URL configured", }, ], }; case "clear_rpc_url": const oldUrl = this.defaultRpcUrl; this.defaultRpcUrl = null; return { content: [ { type: "text", text: oldUrl ? `Cleared default RPC URL: ${oldUrl}` : "No default RPC URL was configured", }, ], }; } switch (name) { case "node_health": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const health = await nodeClient.getHealth(); return { content: [ { type: "text", text: JSON.stringify(health, null, 2), }, ], }; } case "sync_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const syncStatus = await nodeClient.getSyncStatus(); return { content: [ { type: "text", text: JSON.stringify(syncStatus, null, 2), }, ], }; } case "node_peers": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const peers = await nodeClient.getPeers(); return { content: [ { type: "text", text: JSON.stringify(peers, null, 2), }, ], }; } case "arbos_version": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); const version = await chainDataClient.getArbOSVersion(); return { content: [ { type: "text", text: `ArbOS Version: ${version}`, }, ], }; } case "latest_block": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); const latestBlock = await chainDataClient.getLatestBlock(); return { content: [ { type: "text", text: JSON.stringify(latestBlock, null, 2), }, ], }; } case "get_balance": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const ethereumAccountClient = new EthereumAccountClient(rpcUrl); const balance = await ethereumAccountClient.getBalance( args.address as string ); return { content: [ { type: "text", text: `Balance: ${balance} wei`, }, ], }; } case "get_balance_ether": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const ethereumAccountClient = new EthereumAccountClient(rpcUrl); const balanceEth = await ethereumAccountClient.getBalanceInEther( args.address as string ); return { content: [ { type: "text", text: `Balance: ${balanceEth} ETH`, }, ], }; } case "get_transaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const ethereumAccountClient = new EthereumAccountClient(rpcUrl); const tx = await ethereumAccountClient.getTransaction( args.txHash as string ); return { content: [ { type: "text", text: JSON.stringify(tx, null, 2), }, ], }; } case "get_transaction_receipt": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const ethereumAccountClient = new EthereumAccountClient(rpcUrl); const receipt = await ethereumAccountClient.getTransactionReceipt( args.txHash as string ); return { content: [ { type: "text", text: JSON.stringify(receipt, null, 2), }, ], }; } case "is_contract": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const ethereumAccountClient = new EthereumAccountClient(rpcUrl); const isContract = await ethereumAccountClient.isContract( args.address as string ); return { content: [ { type: "text", text: `Is contract: ${isContract}`, }, ], }; } case "list_chains": const chainNames = await this.chainLookupService.listChainNames(); return { content: [ { type: "text", text: `Available chains:\n${chainNames.join("\n")}`, }, ], }; case "search_chains": const searchResults = await this.chainLookupService.searchChains( args.query as string ); return { content: [ { type: "text", text: searchResults.length > 0 ? `Found chains:\n${searchResults .map((c) => `${c.name} (ID: ${c.chainId})`) .join("\n")}` : `No chains found matching "${args.query}"`, }, ], }; case "chain_info": const chainInfo = await this.chainLookupService.findChainByName( args.chainName as string ); if (!chainInfo) { return { content: [ { type: "text", text: `Chain "${args.chainName}" not found`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify(chainInfo, null, 2), }, ], }; case "get_rollup_address": const rollupChainInfo = await this.chainLookupService.findChainByName( args.chainName as string ); if (!rollupChainInfo) { return { content: [ { type: "text", text: `Chain "${args.chainName}" not found`, }, ], }; } if (!rollupChainInfo.rollup) { return { content: [ { type: "text", text: `Rollup contract address not available for ${rollupChainInfo.name}`, }, ], }; } return { content: [ { type: "text", text: `${rollupChainInfo.name} rollup contract address: ${rollupChainInfo.rollup}`, }, ], }; // ========== NEW ARBITRUM NODE METHODS ========== case "arb_check_publisher_health": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const health = await nodeClient.checkPublisherHealth(); return { content: [ { type: "text", text: JSON.stringify(health, null, 2), }, ], }; } case "arb_get_raw_block_metadata": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const fromBlock = (args.fromBlock as number) || 0; const toBlock = (args.toBlock as number) || fromBlock; const metadata = await nodeClient.getRawBlockMetadata( fromBlock, toBlock ); return { content: [ { type: "text", text: JSON.stringify(metadata, null, 2), }, ], }; } case "arb_latest_validated": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const validated = await nodeClient.getLatestValidated(); return { content: [ { type: "text", text: JSON.stringify(validated, null, 2), }, ], }; } case "arbtrace_call": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceCall( args.callArgs, (args.traceTypes as string[]) || ["trace"], args.blockNumOrHash as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbtrace_callMany": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceCallMany( args.calls as any[], args.blockNumOrHash as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } 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), }, ], }; } case "arbtrace_replayTransaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.replayTransaction( args.txHash as string, (args.traceTypes as string[]) || ["trace"] ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbtrace_transaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceTransaction( args.txHash as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbtrace_get": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceGet( args.txHash as string, (args.path as string[]) || [] ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbtrace_block": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceBlock( args.blockNumOrHash as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbtrace_filter": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.traceFilter(args.filter); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbdebug_validateMessageNumber": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.validateMessageNumber( args.msgNum as number, (args.full as boolean) || false, args.moduleRoot as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "arbdebug_validationInputsAt": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.getValidationInputsAt( args.msgNum as number, args.target as string ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "maintenance_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.getMaintenanceStatus(); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "maintenance_trigger": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.triggerMaintenance(); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "timeboost_sendExpressLaneTransaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.sendExpressLaneTransaction( args.submission ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "auctioneer_submitAuctionResolutionTransaction": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const nodeClient = new NitroNodeClient(rpcUrl); const result = await nodeClient.submitAuctionResolutionTransaction( args.transaction ); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } case "batch_posting_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); const status = await chainDataClient.getBatchPostingStatus( args.parentRpcUrl as string, args.sequencerInboxAddress as string, args.bridgeAddress as string ); return { content: [ { type: "text", text: JSON.stringify(status, null, 2), }, ], }; } case "assertion_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); const status = await chainDataClient.getAssertionStatus( args.parentRpcUrl as string, args.rollupAddress as string ); return { content: [ { type: "text", text: JSON.stringify(status, null, 2), }, ], }; } case "gas_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); const status = await chainDataClient.getGasStatus(); return { content: [ { type: "text", text: JSON.stringify(status, null, 2), }, ], }; } case "comprehensive_chain_status": { const rpcUrl = await this.resolveRpcUrl( (args.rpcUrl as string) || (args.chainName as string) ); const chainDataClient = new ArbitrumChainClient(rpcUrl); // Get chain info to auto-populate contract addresses let chainInfo = null; if (args.chainName) { chainInfo = await this.chainLookupService.findChainByName(args.chainName as string); } const parentRpcUrl = args.parentRpcUrl as string || (chainInfo?.parentChainId === 1 ? "https://eth.llamarpc.com" : "https://arb1.arbitrum.io/rpc"); const sequencerInboxAddress = args.sequencerInboxAddress as string || chainInfo?.ethBridge?.sequencerInbox || ""; const bridgeAddress = args.bridgeAddress as string || chainInfo?.ethBridge?.bridge || ""; const rollupAddress = args.rollupAddress as string || chainInfo?.ethBridge?.rollup || ""; const chainName = args.chainName as string || chainInfo?.name || "Unknown Chain"; const status = await chainDataClient.getComprehensiveChainStatus( chainName, parentRpcUrl, sequencerInboxAddress, bridgeAddress, rollupAddress ); return { content: [ { type: "text", text: JSON.stringify(status, null, 2), }, ], }; } default: throw new Error(`Unknown tool: ${name}`); } } catch (error) { console.error("Error in call tool handler:", error); throw error; } }); } private getAvailableTools(): Tool[] {
• src/clients/nitro-node-client.ts:448-464 (helper)

  Helper method in NitroNodeClient that performs the actual RPC call to timeboost_sendExpressLaneTransaction with the submission parameter, handling success/error responses.
  async sendExpressLaneTransaction( submission: any ): Promise<{ success: boolean; error?: string }> { try { await this.makeRpcCall("timeboost_sendExpressLaneTransaction", [ submission, ]); return { success: true }; } catch (error) { return { success: false, error: `Express lane transaction not supported on this RPC endpoint: ${ (error as Error).message }`, }; } }