Content
# arbitrum-mcp
MCP server exposing Arbitrum blockchain capabilities as tools to any MCP-compatible AI agent (Claude, Cursor, etc.)
## Features
- **9 blockchain tools** accessible via MCP protocol
- **Read**: ETH balances, ERC-20 balances, ARB price, contract reads, transaction details
- **Write**: Token swaps (Relay.link), cross-chain bridging (Relay.link), contract deployment, agent registration (ERC-8004)
- **Multi-chain bridging**: Bridge from Ethereum, Base, or BSC to Arbitrum
- **Dual network**: Arbitrum One (mainnet) + Arbitrum Sepolia (testnet)
## Stack
- **Runtime**: Cloudflare Workers
- **Framework**: Hono
- **Protocol**: MCP over Streamable HTTP
- **Chain**: viem
- **Bridge**: Relay.link
## Install Skill
```bash
npx skills add https://github.com/starc007/arbitrum-mcp --skill arbitrum-mcp
```
## Quick Start
```bash
# Install
bun install
# Run locally
bun run dev
# Deploy
bun run deploy
```
## Configuration
### Required
Set your wallet private key as a Cloudflare Worker secret:
```bash
bunx wrangler secret put PRIVATE_KEY
```
### Optional
These have defaults in `wrangler.toml` and can be overridden:
| Variable | Default | Description |
| -------------------------- | ------------------------------------------------ | ------------------------------ |
| `ARBITRUM_RPC_URL` | `https://arb1.arbitrum.io/rpc` | Arbitrum One RPC |
| `ARBITRUM_SEPOLIA_RPC_URL` | `https://sepolia-rollup.arbitrum.io/rpc` | Arbitrum Sepolia RPC |
| `ETH_RPC_URL` | `https://0xrpc.io/eth` | Ethereum L1 RPC (for bridging) |
| `ETH_SEPOLIA_RPC_URL` | `https://eth-sepolia-testnet.api.pocket.network` | Sepolia L1 RPC (for bridging) |
| `BASE_RPC_URL` | `https://base.api.pocket.network` | Base RPC (for bridging) |
| `BSC_RPC_URL` | `https://public-bsc-mainnet.fastnode.io` | BSC RPC (for bridging) |
## Tools
| Tool | Description | Requires Key |
| -------------------- | ---------------------------------------------- | :----------: |
| `get_eth_balance` | ETH balance of any address | |
| `get_token_balance` | ERC-20 balance with symbol/decimals | |
| `get_arb_price` | ARB/USD price from Chainlink oracle | |
| `read_contract` | Call any read-only contract function | |
| `get_transaction` | Transaction details + receipt by hash | |
| `swap_tokens` | Swap any token pair on Arbitrum via Relay.link | Yes |
| `bridge_to_arbitrum` | Bridge from Ethereum/Base/BSC via Relay.link | Yes |
| `deploy_contract` | Deploy contract from bytecode | Yes |
| `register_agent` | Register on ERC-8004 Identity Registry | Yes |
## Agent Registration
Register your agent on the Arbitrum Identity Registry (ERC-8004):
```bash
# Create .env with your private key
cp .env.example .env
# Run registration on Sepolia
bun run register
```
Registry addresses:
- **Arbitrum One**: `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
- **Arbitrum Sepolia**: `0x8004A818BFB912233c491871b3d84c89A494BD9e`
## Project Structure
```
arbitrum-mcp/
├── src/
│ ├── index.ts # Hono app + MCP endpoint
│ ├── server.ts # MCP server + tool registration
│ ├── tools/
│ │ ├── balance.ts # get_eth_balance, get_token_balance
│ │ ├── price.ts # get_arb_price
│ │ ├── contract.ts # read_contract
│ │ ├── transaction.ts # get_transaction
│ │ ├── swap.ts # swap_tokens
│ │ ├── bridge.ts # bridge_to_arbitrum
│ │ ├── deploy.ts # deploy_contract
│ │ └── registry.ts # register_agent
│ └── lib/
│ ├── clients.ts # viem client factories
│ └── constants.ts # addresses, ABIs, chain config
├── scripts/
│ └── register-agent.ts # Standalone registration script
├── skills/
│ └── arbitrum-mcp/
│ └── SKILL.md # MCP skill documentation
├── wrangler.toml
└── package.json
```
## MCP Endpoint
```
POST /mcp
Headers:
Content-Type: application/json
Accept: application/json, text/event-stream
```
The server uses MCP Streamable HTTP transport. Connect any MCP-compatible client to `https://your-worker.workers.dev/mcp`.
## License
MIT
