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

> Discover the main components of the Arbitrum MCP Server including the entry point, specialized clients like NitroNodeClient, and the ChainLookupService. Learn about its architecture and implementation.

- Repository: [Dewansh/arbitrum-mcp](https://github.com/dewanshparashar/arbitrum-mcp)
- Tags: architecture
- Published: 2026-02-28

---

**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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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):

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

```

**Node.js/CLI Deployment**:

```bash
npm install
npm run build
npm start

```

The `Dockerfile` and [`docker-compose.yml`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/index.ts)): Entry point that handles MCP protocol wiring and request routing
- **`NitroNodeClient`** ([`src/clients/nitro-node-client.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/src/clients/ethereum-account-client.ts)): Standard Ethereum account operations including balances and transaction receipts
- **`ChainLookupService`** ([`src/services/chain-lookup.ts`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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`](https://github.com/dewanshparashar/arbitrum-mcp/blob/main/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.