Etherscan MCP

Etherscan MCP Skill

Use this skill to run Etherscan MCP operations through uxc.

Reuse the uxc skill for shared protocol discovery, output parsing, and generic auth/binding flows.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://mcp.etherscan.io/mcp.
• An Etherscan API key is available for authenticated calls.

Core Workflow

1. Confirm endpoint and protocol with help-first probing:
   • uxc https://mcp.etherscan.io/mcp -h
   • expected unauthenticated behavior today: 401 Unauthorized
2. Configure credential/binding for repeatable auth:
   • uxc auth credential set etherscan-mcp --auth-type bearer --secret-env ETHERSCAN_API_KEY
   • uxc auth credential set etherscan-mcp --auth-type bearer --secret-op op://Engineering/etherscan/api-key
   • uxc auth binding add --id etherscan-mcp --host mcp.etherscan.io --path-prefix /mcp --scheme https --credential etherscan-mcp --priority 100
3. Use fixed link command by default:
   • command -v etherscan-mcp-cli
   • If missing, create it: uxc link etherscan-mcp-cli https://mcp.etherscan.io/mcp
   • etherscan-mcp-cli -h
4. Inspect operation schema before execution:
   • etherscan-mcp-cli balance -h
   • etherscan-mcp-cli tokenTopHolders -h
   • etherscan-mcp-cli getContractAbi -h
   • etherscan-mcp-cli transaction -h
5. Prefer read operations first, then any workflow that could trigger heavy data pulls or follow-up automation.

Capability Map

• Address investigation:
  • balance
  • tokenHoldings
  • fundedBy
  • getAddressMetadata
• Token holder analysis:
  • balanceERC20
  • balanceERC20Historical
  • tokenTopHolders
  • getTokenInfo
• Transaction investigation:
  • txList
  • internalTxsByAddress
  • erc20Transfers
  • erc721Transfers
  • erc1155Transfers
  • transaction
  • checkTransaction
• Contract research:
  • getContractAbi
  • getContractSourceCode
  • getContractCreation
• Verification:
  • verifySourceCode
  • checkVerifyStatus

Inspect etherscan-mcp-cli -h after auth setup for the current full tool list. Etherscan can expand MCP tools independently of this wrapper skill.

Recommended Usage Pattern

1. Start from a read-only investigation goal:
   • balance or holdings for an address
   • holder concentration for a token
   • transaction inspection for a hash
   • source/metadata lookup for a contract
2. Run -h on the specific tool before the first real call.
3. Prefer one chain/address/token at a time before broadening the scope.
4. Parse the JSON envelope first, then inspect data.

Guardrails

• Keep automation on JSON output envelope; do not rely on --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Use etherscan-mcp-cli as default command path.
• etherscan-mcp-cli ... is equivalent to uxc https://mcp.etherscan.io/mcp ....
• If unauthenticated probe or runtime call returns 401 Unauthorized:
  • confirm auth binding matches endpoint with uxc auth binding match https://mcp.etherscan.io/mcp
  • confirm credential shape with uxc auth credential info etherscan-mcp
  • reset credential as bearer if needed: uxc auth credential set etherscan-mcp --auth-type bearer --secret-env ETHERSCAN_API_KEY
• Use key=value only for simple scalar inputs.
• Prefer positional JSON when an operation accepts nested objects, arrays, or optional flags that may evolve.
• Do not assume tool argument names from memory; inspect -h first because Etherscan may revise MCP schemas independently of this skill.
• Some MCP tools are tier-gated by Etherscan plan. Today getTokenInfo can return NOTOK with an API Pro upgrade message on non-Pro keys.
• Treat verifySourceCode as a write-like action requiring explicit user confirmation.

References

• Invocation patterns:
  • references/usage-patterns.md