Arbitrum MCP Tools 🚀🦾

This project provides a set of tools for interacting with the Arbitrum blockchain via the Model Context Protocol (MCP), enabling AI assistants like Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Antigravity, and OpenAI Codex to perform blockchain operations.

⚠️ IMPORTANT: Security & Responsibility Notice

This toolkit gives AI assistants the ability to read blockchain data and execute on-chain operations (contract deployment, transaction simulation, etc.) on your behalf. By using these tools, you accept full responsibility for all actions performed through them.

• Always review AI-suggested actions before confirming. AI assistants may misinterpret your intent or produce unexpected results.
• Never share your private keys or API keys. Environment variables containing sensitive credentials (STYLUS_PRIVATE_KEY, ALCHEMY_API_KEY, etc.) should be treated with the same care as passwords.
• Use testnets first. Before performing any on-chain operation on Arbitrum mainnet, test on Arbitrum Sepolia to verify the expected behavior.
• Understand what you approve. When an AI assistant proposes a transaction, deployment, or contract interaction, make sure you understand what it does before allowing execution.
• The authors of this project are not liable for any financial losses, unintended transactions, or damages resulting from the use of these tools. Use at your own risk.

This software is provided "as is", without warranty of any kind. On-chain actions are irreversible — proceed with caution.

Table of Contents 📚

• Quick Start
• Prerequisites
• Supported Platforms
• Environment Variables
• CLI Commands
• Available Tools
• Example Usage
• Development Guide

Quick Start 🚀

Install Arbitrum MCP Tools to your AI assistant with a single command:

npx arbitrum-mcp-tools install

This launches an interactive wizard that guides you through the setup process.

Prerequisites 📝

• Node.js v20.x or higher
• npm (comes with Node.js)
• Alchemy API Key (sign up at https://www.alchemy.com/)
• Arbiscan API Key (optional, sign up at https://arbiscan.io) - Required for the decodeTransactionCalldata tool

Supported Platforms 🖥️

Arbitrum MCP Tools supports 8 platforms across macOS, Windows, and Linux:

| Platform | Format | Status | |----------|--------|--------| | Claude Desktop | JSON | ✅ Supported | | Claude Code | JSON | ✅ Supported | | Cursor | JSON | ✅ Supported | | Windsurf | JSON | ✅ Supported | | VS Code | JSON | ✅ Supported | | Gemini CLI | JSON | ✅ Supported | | Antigravity | JSON | ✅ Supported | | OpenAI Codex | TOML | ✅ Supported |

Environment Variables 🔐

🔒 Security Best Practices:

• Store private keys in a keystore file (STYLUS_KEYSTORE_PATH) rather than as plain text in environment variables whenever possible.
• Never commit .env files or shell profiles containing API keys to version control.
• Rotate your API keys periodically and revoke any that may have been exposed.
• For production deployments, consider using a hardware wallet or a dedicated secrets manager.

Set these environment variables in your shell profile (~/.zshrc or ~/.bashrc):

# Required
export ALCHEMY_API_KEY="your_alchemy_api_key_here"

# Optional (for transaction decoding)
export ARBISCAN_API_KEY="your_arbiscan_api_key_here"

# Stylus Contract Authentication (choose one method)
# Option 1: Direct private key
export STYLUS_PRIVATE_KEY="your_private_key_here"

# Option 2: Path to private key file
export STYLUS_PRIVATE_KEY_PATH="/path/to/your/private/key/file"

# Option 3: Path to keystore file (most secure)
export STYLUS_KEYSTORE_PATH="/path/to/your/keystore/file"

Then reload your shell: source ~/.zshrc

Windows (PowerShell)

[Environment]::SetEnvironmentVariable("ALCHEMY_API_KEY", "your_key_here", "User")

CLI Commands 🛠️

install

Interactive installation wizard for setting up MCP tools.

npx arbitrum-mcp-tools install

uninstall

Remove MCP tools from selected platforms.

npx arbitrum-mcp-tools uninstall

list

Display all supported platforms and their installation status.

npx arbitrum-mcp-tools list

serve

Start the MCP server (used internally by MCP clients).

npx arbitrum-mcp-tools serve

--help / --version

npx arbitrum-mcp-tools --help
npx arbitrum-mcp-tools --version

Available Tools 🧰

The tools are organized into several categories:

1. Account Analysis - Tools for checking balances, transactions, and tokens
2. Chain Data - Tools for retrieving blockchain data like blocks and transactions
3. Contract Interaction - Tools for interacting with smart contracts
4. Cross-Chain - Tools for cross-chain operations
5. Development - Tools for developers (simulation, gas estimation)
6. Batch Operations - Tools for performing operations on multiple addresses
7. Stylus - Tools for Stylus development and deployment

For a detailed list of all tools, see the Feature Matrix.

Example Usage 📝

When using any supported AI assistant, you can simply ask for blockchain data using natural language:

• "What's the ETH balance of 0x123...?"
• "Check NFTs owned by 0xabc..."
• "How much gas is needed to transfer 1 ETH?"
• "Show me the latest block on Arbitrum"
• "Decode this transaction input data: 0x..."
• "Deploy my Stylus contract to Arbitrum Sepolia"

Development Guide 🏗️

Project Structure 🗂️

src/
├── index.ts                # Entry point (runs server)
├── server.ts               # MCP server setup and Alchemy config
├── cli/                    # CLI installer
│   ├── index.ts            # CLI entry point
│   ├── commands/           # CLI commands (install, uninstall, list, serve)
│   ├── clients/            # Platform config generators
│   └── utils/              # CLI utilities
├── tools/                  # All tools organized by category
│   ├── common.ts           # Shared utilities and configs
│   ├── index.ts            # Tool registration
│   ├── accountAnalysis/    # Account analysis tools
│   ├── chainData/          # Chain data tools
│   ├── contractInteraction/# Contract interaction tools
│   ├── crossChain/         # Cross-chain tools
│   ├── development/        # Development tools
│   ├── batchOperations/    # Batch operation tools
│   └── stylus/             # Stylus development tools

Adding New Tools 🛠️

Arbitrum MCP Tools uses an active registration pattern – every tool is registered at runtime with server.tool(...). To add a new tool:

1. Add the tool to its category's registerXTools function

// src/tools/myCategory/index.ts
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerMyCategoryTools(server: McpServer) {
  server.tool(
    "myNewTool",
    "Short description of what it does",
    {
      param1: z.string().describe("Example parameter"),
    },
    async ({ param1 }) => {
      return {
        content: [{ type: "text", text: `You sent ${param1}` }],
      };
    }
  );
}

2. Hook the category into the global registry

// src/tools/index.ts
import { registerMyCategoryTools } from "./myCategory/index.js";

export function registerAllTools(server: McpServer) {
  // …existing categories
  registerMyCategoryTools(server);
}

Testing Your Tools 🧪

1. Build the project:

npm run build

2. Test the MCP server directly:

node build/src/index.js

3. For testing with an AI assistant, temporarily modify your platform's config to point to the local build:

{
  "mcpServers": {
    "arbitrum": {
      "command": "node",
      "args": ["/path/to/arbitrum-mcp-tools/build/src/index.js"]
    }
  }
}

Tool Documentation Links 🔗

• Alchemy SDK: Alchemy SDK Quickstart
• Arbitrum Stylus: Stylus CLI Usage

Disclaimer ⚖️

This project is an open-source developer tool that connects AI assistants to the Arbitrum blockchain through the Model Context Protocol. It is intended for development, testing, and educational purposes.

Key points:

• All on-chain operations (deployments, transactions, activations) are initiated by the user through their AI assistant. The tool does not perform any action without user interaction.
• The MCP server runs locally on your machine and communicates only with the Alchemy API and Arbitrum RPC endpoints. No data is sent to third-party servers beyond these services.
• Smart contract deployments and on-chain transactions are irreversible. Always verify transaction parameters, target networks, and gas costs before confirming.
• This project does not custody, manage, or have access to your funds. Private keys remain in your local environment and are never transmitted or stored by the tool.
• The authors make no guarantees about the correctness, security, or reliability of AI-generated suggestions. You are solely responsible for reviewing and approving all actions.

By using this software, you acknowledge that you understand the risks associated with blockchain operations and accept full responsibility for any outcomes.

Contributing 🙌

Contributions are welcome! Please feel free to submit a Pull Request.

License 📜

This project is licensed under the MIT License - see the LICENSE file for details.