erc20-mcp: Token Operations

The erc20-mcp server allows agents to interact with ERC-20 tokens across supported chains in a safe, modular, and non-custodial way.

This module enables LLM agents to:

• Check balances

• Transfer tokens

• Approve spending

• Prepare ERC-20 payloads for wallet signing

It operates as a read/write utility layer for token interactions, without ever signing or broadcasting on its own.

---

What It Does

• Fetches token metadata and balances

• Prepares unsigned transfer, approve, or permit transactions

• Returns payloads ready for tools like metamask-mcp to sign

• Works across chains, using resolved RPCs via chainlist-mcp

---

Tool 1: erc20.balanceOf

Request

{
  "tool": "erc20.balanceOf",
  "args": {
    "wallet": "0x123...",
    "token": "USDC",
    "chain": "arbitrum"
  }
}

Response

{
  "token": "USDC",
  "balance": "100.5",
  "decimals": 6,
  "chain": "arbitrum"
}

• token: Ticker or address (resolved internally)

• wallet: Wallet address to check

• chain: Optional — defaults to mainnet

---

Tool 2: erc20.transfer

Request

{
  "tool": "erc20.transfer",
  "args": {
    "to": "0xabc...",
    "amount": "50",
    "token": "USDC",
    "from": "0x123...",
    "chain": "optimism"
  }
}

Response

{
  "unsignedTx": {
    "to": "0xA0b86991c...",
    "data": "0xa9059cbb00000000...",
    "value": "0x0",
    "gas": 60000
  },
  "chainId": 10,
  "explorer": "https://optimistic.etherscan.io"
}

This unsigned transaction can now be passed to metamask-mcp for signing.

---

Tool 3: erc20.approve

Request

{
  "tool": "erc20.approve",
  "args": {
    "spender": "0xrouter...",
    "amount": "100",
    "token": "USDC",
    "chain": "ethereum"
  }
}

Response

{
  "unsignedTx": {
    "to": "0xA0b86991c...",
    "data": "0x095ea7b300000000...",
    "gas": 48000
  },
  "chainId": 1
}

---

Server Setup

To run erc20-mcp locally:

git clone https://github.com/pilso-os/mcp-servers
cd mcp-servers/erc20-mcp
npm install
npm start

Default endpoint: http://localhost:3040

Update pilso.config.json:

"tools": [
  "http://localhost:3040"
]

---

Token Resolution Logic

erc20-mcp supports both:

• Common token names (e.g. USDC, WETH)

• Full contract addresses

If you provide a symbol, it auto-resolves via:

• Chain-specific token maps

• Internal token registry

• Chain ID via chainlist-mcp

To override or customize token maps, you can extend the internal JSONs in /tokens/.

---

Test Call Locally

npx pilso call \
  --tool erc20.balanceOf \
  --args '{"wallet": "0x123...", "token": "USDC", "chain": "polygon"}'

---

Security Best Practices

• Do not expose erc20.transfer to general-purpose roles

• Use role-level guardrails like "Never transfer without confirmation"

• Always preview the unsignedTx in the logs before signing

• Only allow trusted tokens or whitelisted contracts in production agents

---

Future Additions

• Support for EIP-2612 permit() meta-transactions

• Multi-transfer batch support

• AI-assisted gas estimation per chain/token

---

✅ Summary

Property	Value
Tool names	erc20.balanceOf, erc20.transfer, erc20.approve
Port	3040 (default)
Signature	Only prepares payloads — does not sign or broadcast
Chain support	EVM-based chains only
Integrates with	chainlist-mcp, metamask-mcp

erc20-mcp is the token layer of PILSO OS — enabling any role-scoped agent to interact with ERC-20 contracts in a safe, modular way.