Arbitrum MCP Tools 🚀🦾

Arbitrum MCP 工具 🚀🦾

本项目提供一组通过模型上下文协议（MCP）与 Arbitrum 区块链交互的工具，使 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Gemini CLI、Antigravity 和 OpenAI Codex 等 AI 助手能够执行区块链操作。

⚠️ 重要：安全与责任声明

此工具包赋予 AI 助手代表您读取区块链数据并执行链上操作（部署合约、模拟交易等）的能力。使用这些工具，即表示您对通过它们执行的所有操作承担全部责任。

• 确认前，务必检查 AI 建议的操作。 AI 助手可能会误解您的意图，或产生意外结果。
• 切勿分享您的私钥或 API 密钥。 包含敏感凭据（STYLUS_PRIVATE_KEY、ALCHEMY_API_KEY 等）的环境变量应像密码一样妥善保管。
• 请先使用测试网。 在 Arbitrum 主网上执行任何链上操作之前，请先在 Arbitrum Sepolia 上测试，以验证行为是否符合预期。
• 了解您批准的内容。 当 AI 助手提出交易、部署或合约交互时，请在允许执行前确认您了解其作用。
• 本项目作者不承担任何责任，包括因使用这些工具造成的经济损失、非预期交易或损害。使用风险由您自行承担。

本软件按“原样”提供，不附带任何形式的保证。链上操作不可逆——请谨慎操作。

目录 📚

• 快速开始
• 前置条件
• 支持的平台
• 环境变量
• CLI 命令
• 可用工具
• 使用示例
• 开发指南

快速开始 🚀

只需一条命令，即可将 Arbitrum MCP Tools 安装到您的 AI 助手：

npx arbitrum-mcp-tools install

这会启动交互式向导，引导您完成设置过程。

前置条件 📝

• Node.js v20.x 或更高版本
• npm（随 Node.js 一同安装）
• Alchemy API Key（在 https://www.alchemy.com/ 注册）
• Arbiscan API Key（可选，在 https://arbiscan.io 注册）——decodeTransactionCalldata 工具需要此项

支持的平台 🖥️

Arbitrum MCP Tools 支持 macOS、Windows 和 Linux 上的 8 个平台：

平台	格式	状态
Claude Desktop	JSON	✅ 已支持
Claude Code	JSON	✅ 已支持
Cursor	JSON	✅ 已支持
Windsurf	JSON	✅ 已支持
VS Code	JSON	✅ 已支持
Gemini CLI	JSON	✅ 已支持
Antigravity	JSON	✅ 已支持
OpenAI Codex	TOML	✅ 已支持

环境变量 🔐

🔒 安全最佳实践：

• 尽可能将私钥存储在密钥库文件（STYLUS_KEYSTORE_PATH）中，而不是以纯文本形式存放在环境变量中。
• 切勿将包含 API 密钥的 .env 文件或 Shell 配置文件提交到版本控制中。
• 定期轮换 API 密钥，并撤销任何可能已泄露的密钥。
• 对于生产部署，可考虑使用硬件钱包或专用密钥管理器。

在 Shell 配置文件（~/.zshrc 或 ~/.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"

然后重新加载 Shell：source ~/.zshrc

Windows（PowerShell）

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

CLI 命令 🛠️

install

用于设置 MCP 工具的交互式安装向导。

npx arbitrum-mcp-tools install

uninstall

从选定的平台移除 MCP 工具。

npx arbitrum-mcp-tools uninstall

list

显示所有受支持的平台及其安装状态。

npx arbitrum-mcp-tools list

serve

启动 MCP 服务（供 MCP 客户端在内部使用）。

npx arbitrum-mcp-tools serve

--help / --version

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

可用工具 🧰

这些工具分为以下几类：

1. 账户分析 - 用于检查余额、交易和代币的工具
2. 链上数据 - 用于检索区块和交易等区块链数据的工具
3. 合约交互 - 用于与智能合约交互的工具
4. 跨链 - 用于执行跨链操作的工具
5. 开发 - 面向开发者的工具（模拟、Gas 估算）
6. 批量操作 - 用于对多个地址执行操作的工具
7. Stylus - 用于 Stylus 开发和部署的工具

有关所有工具的详细列表，请参阅功能矩阵。

使用示例 📝

使用任何受支持的 AI 助手时，你只需用自然语言询问区块链数据：

• “0x123... 的 ETH 余额是多少？”
• “检查 0xabc... 持有的 NFT。”
• “转账 1 ETH 需要多少 Gas？”
• “显示 Arbitrum 上的最新区块”
• “解码这段交易输入数据：0x...”
• “将我的 Stylus 合约部署到 Arbitrum Sepolia”

开发指南 🏗️

项目结构 🗂️

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

添加新工具 🛠️

Arbitrum MCP Tools 使用动态注册模式——每个工具都会在运行时通过 server.tool(...) 注册。添加新工具的步骤：

1. 将工具添加到所属类别的 registerXTools 函数中

// 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. 将该类别接入全局注册表

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

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

测试你的工具 🧪

1. 构建项目：

npm run build

2. 直接测试 MCP 服务：

node build/src/index.js

3. 如需使用 AI 助手进行测试，请临时修改平台配置，使其指向本地构建版本：

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

工具文档链接 🔗

• Alchemy SDK：Alchemy SDK 快速入门
• Arbitrum Stylus：Stylus CLI 用法

免责声明 ⚖️

本项目是一个开源开发工具，通过 Model Context Protocol 将 AI 助手连接到 Arbitrum 区块链。本项目旨在用于开发、测试和教育目的。

要点：

• 所有链上操作（部署、交易、激活）均由用户通过 AI 助手发起。未经用户交互，工具不会执行任何操作。
• MCP 服务在你的计算机本地运行，且只与 Alchemy API 和 Arbitrum RPC 端点通信。除这些服务外，不会向第三方服务发送任何数据。
• 智能合约部署和链上交易均不可逆。确认前，请务必核实交易参数、目标网络和 Gas 费用。
• 本项目不会托管、管理或访问你的资金。私钥保留在你的本地环境中，工具绝不会传输或存储私钥。
• 作者对 AI 生成建议的正确性、安全性或可靠性不作任何保证。你需独自负责审查并批准所有操作。

使用本软件即表示你确认已了解区块链操作相关风险，并愿意对任何后果承担全部责任。

参与贡献 🙌

欢迎参与贡献！请随时提交 Pull Request。

许可证 📜

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。