EVM Proxy

PyPI version Python License: MIT

MCP server for advanced EVM smart contract analysis with proxy detection, implementation resolution, and security analysis.

A Model Context Protocol server that provides AI assistants with tools to analyze Ethereum and EVM-compatible smart contracts.

Features

• 9 Proxy Pattern Detection - EIP-1967, UUPS, Beacon, Diamond, Minimal Clone, GnosisSafe, and more
• Automatic Implementation Resolution - Follows proxy chains to find the actual logic contract
• Admin Function Detection - Identifies privileged functions (upgrade, pause, mint, burn, etc.)
• Security Analysis - Generates security notes and risk assessments
• Multi-Chain Support - Ethereum, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche

Installation

From PyPI

pip install evm-proxy-mcp

From Source

git clone https://github.com/0xGval/evm-proxy-mcp.git
cd evm-proxy-mcp
pip install -e .

Configuration

With Claude Code

claude mcp add evm-proxy-mcp -e ETHERSCAN_API_KEY=your_api_key -- uvx evm-proxy-mcp

Or with pip installation:

claude mcp add evm-proxy-mcp -e ETHERSCAN_API_KEY=your_api_key -- python -m src.server

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "evm-proxy-mcp": {
      "command": "uvx",
      "args": ["evm-proxy-mcp"],
      "env": {
        "ETHERSCAN_API_KEY": "your_etherscan_api_key"
      }
    }
  }
}

Environment Variables

Variable	Description	Required
ETHERSCAN_API_KEY	Your Etherscan API key (get one free)	Recommended
ETH_RPC_URL	Custom RPC endpoint	Optional

Tools

detect_proxy

Detect proxy pattern for an EVM smart contract.

Parameters:

• address (required): Contract address (0x...)
• chain (optional): Chain name (default: ethereum)
• follow_chain (optional): Follow nested proxies (default: false)

Supported Proxy Patterns:

1. EIP-1967 Transparent Proxy
2. EIP-1967 Beacon Proxy
3. EIP-1822 UUPS Proxy
4. ZeppelinOS Legacy Proxy
5. EIP-1167 Minimal Proxy Clone
6. GnosisSafe Proxy
7. Diamond Proxy (EIP-2535)
8. EIP-897 DelegateProxy
9. Custom/Unknown Proxy

get_contract_source

Fetch verified source code for a smart contract.

Parameters:

• address (required): Contract address (0x...)
• chain (optional): Chain name (default: ethereum)
• resolve_proxy (optional): Also fetch implementation source (default: true)

analyze_abi

Analyze contract ABI for security-relevant information.

Parameters:

• address (required): Contract address (0x...)
• chain (optional): Chain name (default: ethereum)
• include_full_abi (optional): Include full function list (default: false)

Detects:

• Upgrade functions
• Pause/unpause capabilities
• Mint/burn functions
• Ownership management
• Blacklist/whitelist
• Self-destruct capability

get_contract_creation

Get contract deployer address and creation transaction.

Parameters:

• address (required): Contract address (0x...)
• chain (optional): Chain name (default: ethereum)

full_analysis

Perform comprehensive contract analysis combining all tools.

Parameters:

• address (required): Contract address (0x...)
• chain (optional): Chain name (default: ethereum)

list_chains

List all supported blockchain networks.

Supported Chains

Chain	Chain ID
ethereum	1
sepolia	11155111
polygon	137
arbitrum	42161
optimism	10
base	8453
bsc	56
avalanche	43114

Example Usage

Analyze USDC Contract

User: Analyze the USDC contract on Ethereum

Claude: [Uses full_analysis tool with address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48]

## Analysis Results

### Proxy Status
- **Is Proxy**: Yes
- **Type**: EIP-1967 Transparent Proxy
- **Implementation**: 0x43506...

### Admin Functions Detected
- pause()
- unpause()
- blacklist(address)
- mint(address,uint256)

### Security Notes
- Contract can be paused - centralization risk
- Contract has blacklist functionality
- Contract has mint capabilities

Check if Contract is a Proxy

User: Is 0x1234... a proxy contract?

Claude: [Uses detect_proxy tool]

The contract at 0x1234... is an EIP-1967 Transparent Proxy.
- Implementation: 0x5678...
- Admin: 0x9abc...

Development

Setup

git clone https://github.com/0xGval/evm-proxy-mcp.git
cd evm-proxy-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

pytest

Run in Development Mode

python run.py

Architecture

src/
├── __init__.py        # Package metadata
├── server.py          # MCP server entry point
├── config.py          # Storage slots, selectors, chain configs
├── client.py          # Etherscan API client
├── proxy_detector.py  # 9 proxy pattern detection
└── abi_analyzer.py    # ABI analysis + admin detection

How Proxy Detection Works

The server detects proxies by:

1. Bytecode Analysis - Checks for EIP-1167 minimal proxy pattern in bytecode
2. Storage Slot Reading - Reads standardized EIP-1967 storage slots
3. Function Calls - Tries common implementation getter functions

Storage Slots Used

Pattern	Slot
EIP-1967 Implementation	0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc
EIP-1967 Admin	0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103
EIP-1967 Beacon	0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50
EIP-1822 UUPS	0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Author

0xGval - GitHub

---

Built for the Model Context Protocol ecosystem.