# 🛡️ EVM MCP Auditor

[![CI Test Suite](https://github.com/zalana28/evm-mcp-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/zalana28/evm-mcp-auditor/actions/workflows/ci.yml)
[![M8ven Trust Score](https://m8ven.ai/badge/mcp/zalana28-evm-mcp-auditor-1w5o9p)](https://m8ven.ai/mcp/zalana28-evm-mcp-auditor-1w5o9p)
[![Glama Registry](https://img.shields.io/badge/Glama-Registry-6366f1.svg)](https://glama.ai/mcp/servers/d80plnk6uh)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP Protocol](https://img.shields.io/badge/MCP-1.0.0-cyan.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178c6.svg?logo=typescript)](https://www.typescriptlang.org)

> **Production-grade Model Context Protocol (MCP) server for EVM Smart Contract security auditing, static vulnerability analysis, and multi-chain telemetry for Claude & Claude Code.**

---

## ⚡ Overview

**EVM MCP Auditor** connects Anthropic's **Claude**, **Claude Desktop**, and **Claude Code CLI** directly to Ethereum and EVM ecosystems. It equips Claude with specialized security auditing tools to automatically inspect Solidity smart contracts for critical attack vectors, fetch verified source code from block explorers, decode raw transaction calldata, and estimate multi-chain gas costs.

```
┌───────────────────────────┐         ┌───────────────────────────────┐
│                           │  stdio  │                               │
│  Claude Desktop / Code    │ ◄─────► │  EVM MCP Auditor Server       │
│  (Anthropic AI)           │         │  (@zalana/evm-mcp-auditor)    │
│                           │         │                               │
└───────────────────────────┘         └──────────────┬────────────────┘
                                                     │
                                                     ▼
                                      ┌───────────────────────────────┐
                                      │  EVM Networks & Explorers     │
                                      │  • Ethereum • Base • Arbitrum │
                                      │  • Optimism • Polygon • BSC   │
                                      └───────────────────────────────┘
```

---

## 🚀 Features & MCP Tools

| MCP Tool | Description |
| :--- | :--- |
| `evm_audit_contract` | Run static security analysis on Solidity code (Reentrancy, Unsafe Delegatecall, `tx.origin` auth, Unchecked Calls, Timestamp Dependency, Selfdestruct). |
| `evm_fetch_source` | Pull verified contract source code directly from block explorers across 6 EVM networks. |
| `evm_decode_calldata` | Decode raw transaction hex data into 4-byte function selectors and parameter chunks. |
| `evm_estimate_gas` | Fetch real-time gas telemetry across Ethereum, Base, Arbitrum, Polygon, Optimism, and BSC. |

---

## 📦 Quickstart & Installation

### Option 1: Claude Desktop Integration
Add the following snippet to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "evm-auditor": {
      "command": "npx",
      "args": ["-y", "@zalana/evm-mcp-auditor"]
    }
  }
}
```

### Option 2: Claude Code CLI
```bash
claude mcp add evm-auditor npx -y @zalana/evm-mcp-auditor
```

### Option 3: Local Development
```bash
# Clone repository
git clone https://github.com/zalana28/evm-mcp-auditor.git
cd evm-mcp-auditor

# Install dependencies
npm install

# Run automated test suites
npm test

# Build TypeScript to dist/
npm run build

# Run local MCP server
npm start
```

---

## 🛡️ Supported Vulnerability Scanners (SWC / CWE)

- **EVM-SEC-001**: Reentrancy (Checks-Effects-Interactions violation) `SWC-107` / `CWE-841`
- **EVM-SEC-002**: Arbitrary / Uncontrolled Delegatecall `SWC-112` / `CWE-829`
- **EVM-SEC-003**: Vulnerable Authentication via `tx.origin` `SWC-115` / `CWE-287`
- **EVM-SEC-004**: Unchecked Return Value of Low-Level Call `SWC-104` / `CWE-252`
- **EVM-SEC-005**: Block Timestamp Manipulation `SWC-116` / `CWE-330`
- **EVM-SEC-006**: Deprecated `selfdestruct` / Unprotected State Lock `SWC-106` / `CWE-284`
- **EVM-SEC-007**: Floating Pragma Compiler Warning `SWC-103` / `CWE-664`
- **EVM-SEC-008**: Missing Zero-Address (`address(0)`) Setter Validation `SWC-100` / `CWE-20`

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome! Please check the [Contributing Guide](CONTRIBUTING.md).

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

<sub>Built with ⚡ by [Zalana](https://github.com/zalana28) for the global Open-Source and Web3 developer community.</sub>