Main Components of the Arbitrum MCP Server: Architecture and Implementation Guide

The Arbitrum MCP Server consists of five core components: the ArbitrumMCPServer entry point, three specialized clients (NitroNodeClient, ArbitrumChainClient, EthereumAccountClient), and the ChainLookupService for chain discovery.

The Arbitrum MCP (Model Context Protocol) Server is a modular TypeScript application that exposes blockchain data and node operations as natural-language tools. Understanding the main components of the Arbitrum MCP Server is essential for developers integrating Arbitrum Nitro node functionality into AI assistants or automated workflows.

Core Architecture Overview

The server follows a clean separation of concerns between transport handling, domain-specific blockchain operations, and chain discovery. At runtime, the ArbitrumMCPServer class in src/index.ts initializes all clients and exposes their methods as MCP-compatible tools through the getAvailableTools registry.

The Five Main Components of the Arbitrum MCP Server

1. ArbitrumMCPServer (Entry Point and MCP Wrapper)

The ArbitrumMCPServer class serves as the primary entry point and MCP protocol handler. Located in src/index.ts (lines 15-22), this component:

• Creates the MCP Server instance using the official MCP SDK
• Wires request handlers for tool invocations
• Resolves RPC URLs, including auto-lookup of chain names via the ChainLookupService
• Holds the default RPC configuration for fallback connections

When a client sends a request, the server routes it to the appropriate client method based on the tool name defined in the registry.

2. NitroNodeClient (Nitro Node Admin Operations)

The NitroNodeClient in src/clients/nitro-node-client.ts (lines 60-68) provides direct RPC access to Arbitrum Nitro node administrative APIs. This client handles all "arb*" and "arbtrace*" prefixed tools, including:

• Node health and synchronization: arb_node_health, arb_syncing
• Peer management: arb_peer_count, arb_peer_urls
• Tracing and debugging: arbtrace_call, arbtrace_transaction
• Maintenance operations: arb_start_caching, arb_stop_caching
• Time-boost and auctioneer: arb_time_boost, arb_auctioneer_status

This component requires direct access to a Nitro node's RPC endpoint, typically running on localhost or a dedicated node infrastructure.

3. ArbitrumChainClient (Chain-Wide Status Monitoring)

Located in src/clients/arbitrum-chain-client.ts (lines 35-43), the ArbitrumChainClient offers high-level, read-only queries for chain-wide Arbitrum-specific data. This client powers the monitoring tools by exposing:

• ArbOS version detection: arbos_version
• Batch posting status: batch_posting_status (checks sequencer inbox health)
• Assertion status: assertion_status (validates rollup state assertions)
• Gas price monitoring: gas_status (current network gas prices in gwei)
• Composite health check: comprehensive_chain_status (aggregates all metrics above)

Unlike the NitroNodeClient, this client works with any standard Arbitrum RPC endpoint and does not require node admin access.

4. EthereumAccountClient (Account and Transaction Queries)

The EthereumAccountClient in src/clients/ethereum-account-client.ts (lines 29-37) provides basic Ethereum JSON-RPC functionality for account-centric operations. This component handles standard Ethereum queries that work across any EVM-compatible chain, including Arbitrum:

• Balance queries: get_balance (wei), get_balance_ether (ETH formatted)
• Transaction inspection: get_transaction, get_transaction_receipt
• Contract detection: is_contract (checks if address contains code)

This client ensures the MCP server can handle standard Ethereum operations without requiring Arbitrum-specific APIs.

5. ChainLookupService (Orbit Chain Discovery)

The ChainLookupService in src/services/chain-lookup.ts (lines 59-67) functions as a singleton discovery service for Arbitrum Orbit chains. This component solves the "which RPC URL?" problem by:

• Caching chain metadata: Fetches and caches a public JSON file containing Arbitrum Orbit chain configurations
• Core chain fallback: Includes hardcoded entries for Arbitrum One and Arbitrum Nova
• Name resolution: findChainByName() resolves human-readable names (e.g., "Xai") to RPC URLs
• Search functionality: searchChains() allows fuzzy matching across the chain database

When users specify a chainName parameter in tools rather than a raw RPC URL, this service performs the lookup automatically.

Tool Registry and MCP Integration

The getAvailableTools method (located in src/index.ts, lines 21-30) generates the MCP tool description list that advertises capabilities to MCP-compatible clients like Claude or Cline. Each entry in the registry includes:

• Tool name: Maps to the corresponding client method
• Description: Natural language explanation for AI agents
• JSON Schema: Parameter validation schema (rpcUrl, chainName, address, etc.)

This registry enables the dynamic discovery of all available blockchain operations without hardcoding tool lists in client applications.

Deployment Options

The repository provides multiple deployment paths for the main components:

Docker Deployment (recommended for production):

docker run -i --rm dewanshparashar/arbitrum-mcp

Node.js/CLI Deployment:

npm install
npm run build
npm start

The Dockerfile and docker-compose.yml in the repository root handle dependency installation and TypeScript compilation automatically.

Summary

The main components of the Arbitrum MCP Server provide a modular architecture for blockchain interaction:

• ArbitrumMCPServer (src/index.ts): Entry point that handles MCP protocol wiring and request routing
• NitroNodeClient (src/clients/nitro-node-client.ts): Direct RPC access to Nitro node admin APIs for health, tracing, and maintenance
• ArbitrumChainClient (src/clients/arbitrum-chain-client.ts): High-level chain monitoring for ArbOS versions, batch posting, assertions, and gas prices
• EthereumAccountClient (src/clients/ethereum-account-client.ts): Standard Ethereum account operations including balances and transaction receipts
• ChainLookupService (src/services/chain-lookup.ts): Discovery service that resolves Arbitrum Orbit chain names to RPC endpoints

Together, these components enable AI agents and automated systems to query Arbitrum blockchain data through a standardized Model Context Protocol interface.

Frequently Asked Questions

What is the Arbitrum MCP Server?

The Arbitrum MCP Server is a TypeScript-based Model Context Protocol (MCP) implementation that exposes Arbitrum blockchain operations as natural-language tools. According to the dewanshparashar/arbitrum-mcp source code, it wraps Nitro node APIs, chain monitoring functions, and Ethereum account queries into a standardized interface that AI assistants like Claude can interact with via JSON-RPC over STDIO.

How does the NitroNodeClient differ from ArbitrumChainClient?

The NitroNodeClient (src/clients/nitro-node-client.ts) requires direct access to an Arbitrum Nitro node's administrative RPC endpoints and handles low-level node operations like health checks, peer management, tracing (arbtrace_call), and maintenance modes. In contrast, the ArbitrumChainClient (src/clients/arbitrum-chain-client.ts) works with standard public RPC endpoints to provide high-level chain monitoring including ArbOS versions, batch posting status, and gas price tracking without requiring node admin privileges.

Can I run the Arbitrum MCP Server without Docker?

Yes, the Arbitrum MCP Server supports native Node.js execution. As implemented in the repository's src/index.ts entry point, you can run npm install to install dependencies, npm run build to compile the TypeScript, and npm start to launch the MCP STDIO server. The repository also includes a Dockerfile and docker-compose.yml for containerized deployment, but these are optional for local development or integration into existing Node.js environments.

How does the server handle chain discovery for Orbit chains?

The server uses the ChainLookupService (src/services/chain-lookup.ts) to handle Arbitrum Orbit chain discovery. This singleton service fetches and caches a public JSON file containing metadata for all registered Orbit chains, while maintaining hardcoded entries for Arbitrum One and Nova. When a tool request includes a chainName parameter (e.g., "Xai" or "Superposition"), the service resolves it to the appropriate RPC URL using the findChainByName() method, eliminating the need for users to manually configure endpoints for every Orbit chain they want to query.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}