# EVM Proxy MCP

[![PyPI version](https://img.shields.io/pypi/v/evm-proxy-mcp.svg)](https://pypi.org/project/evm-proxy-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/evm-proxy-mcp.svg)](https://pypi.org/project/evm-proxy-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

A [Model Context Protocol](https://modelcontextprotocol.io/) 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

```bash
pip install evm-proxy-mcp
```

### From Source

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

## Configuration

### With Claude Code

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

Or with pip installation:

```bash
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`:

```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](https://etherscan.io/apis)) | 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

```bash
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

```bash
pytest
```

### Run in Development Mode

```bash
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](CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

**0xGval** - [GitHub](https://github.com/0xGval)

---

Built for the [Model Context Protocol](https://modelcontextprotocol.io/) ecosystem.