Arbitrum MCP Tools
MCP server: Arbitrum MCP Tools
Installation
npx arbitrum-mcp-toolsAsk AI about Arbitrum MCP Tools
Powered by Claude Β· Grounded in docs
I know everything about Arbitrum MCP Tools. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
decodeTransactionCalldatatool
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
.envfiles 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:
- Account Analysis - Tools for checking balances, transactions, and tokens
- Chain Data - Tools for retrieving blockchain data like blocks and transactions
- Contract Interaction - Tools for interacting with smart contracts
- Cross-Chain - Tools for cross-chain operations
- Development - Tools for developers (simulation, gas estimation)
- Batch Operations - Tools for performing operations on multiple addresses
- 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:
- Add the tool to its category's
registerXToolsfunction
// 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}` }],
};
}
);
}
- 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 π§ͺ
- Build the project:
npm run build
- Test the MCP server directly:
node build/src/index.js
- 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.
