| name | etherscan-mcp-skill |
| description | Use Etherscan MCP through UXC for address balance checks, token holder analysis, transaction inspection, and contract lookup tasks. Use when tasks need Etherscan MCP tools for onchain investigation with help-first schema inspection, bearer-key auth, and tier-aware read-first handling. |
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
- Confirm endpoint and protocol with help-first probing:
uxc https://mcp.etherscan.io/mcp -h- expected unauthenticated behavior today:
401 Unauthorized
- Configure credential/binding for repeatable auth:
uxc auth credential set etherscan-mcp --auth-type bearer --secret-env ETHERSCAN_API_KEYuxc auth credential set etherscan-mcp --auth-type bearer --secret-op op://Engineering/etherscan/api-keyuxc auth binding add --id etherscan-mcp --host mcp.etherscan.io --path-prefix /mcp --scheme https --credential etherscan-mcp --priority 100
- 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
- Inspect operation schema before execution:
etherscan-mcp-cli balance -hetherscan-mcp-cli tokenTopHolders -hetherscan-mcp-cli getContractAbi -hetherscan-mcp-cli transaction -h
- Prefer read operations first, then any workflow that could trigger heavy data pulls or follow-up automation.
Capability Map
- Address investigation:
balancetokenHoldingsfundedBygetAddressMetadata
- Token holder analysis:
balanceERC20balanceERC20HistoricaltokenTopHoldersgetTokenInfo
- Transaction investigation:
txListinternalTxsByAddresserc20Transferserc721Transferserc1155TransferstransactioncheckTransaction
- Contract research:
getContractAbigetContractSourceCodegetContractCreation
- Verification:
verifySourceCodecheckVerifyStatus
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
- 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
- Run
-h on the specific tool before the first real call.
- Prefer one chain/address/token at a time before broadening the scope.
- 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 <operation> ... is equivalent to uxc https://mcp.etherscan.io/mcp <operation> ....- 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
<operation> -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
