🔒 MCP Contract Auditor

Smart Contract Security Audit MCP Server — Fetch, analyze, and generate audit reports for EVM smart contracts.

Built for CyOps Arena Hackathon by Carlys17.

Features

Tool	Description
audit_contract	🔒 Full audit — fetch source, scan vulns, analyze holders, generate report
fetch_contract	Fetch verified contract source code & ABI from Blockscout
scan_vulns	Scan Solidity source for 15+ vulnerability patterns
check_holders	Analyze token holder distribution & centralization risk
list_chains	List all supported EVM chains

Supported Chains

Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Gnosis, Avalanche, zkSync Era, Celo — all via Blockscout API (no API key required).

Vulnerability Detection

Category	Patterns Detected
🔴 Reentrancy	Classic reentrancy, cross-function reentrancy
🟠 Access Control	Missing modifiers, tx.origin auth
🟠 External Calls	Unchecked low-level calls, delegatecall, selfdestruct
🟡 Integer	Overflow/underflow (pre-0.8), unchecked arithmetic
🟡 Denial of Service	Unbounded loops, forced ether
🟡 ERC-20	Missing return values, approve race condition
🔵 Informational	Floating pragma, inline assembly, timestamp dependence

Installation

# Clone
git clone https://github.com/Carlys17/mcp-contract-auditor.git
cd mcp-contract-auditor

# Install dependencies
npm install

# Build
npm run build

# Run
npm start

Usage with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "contract-auditor": {
      "command": "node",
      "args": ["/path/to/mcp-contract-auditor/dist/index.js"]
    }
  }
}

Example Usage

Full Audit

audit_contract(
  address: "0x1234...abcd",
  chain: "ethereum",
  include_holder_analysis: true
)

Quick Vulnerability Scan

scan_vulns(
  source_code: "pragma solidity ^0.8.0; contract Foo { ... }",
  contract_name: "Foo"
)

Check Token Holders

check_holders(
  address: "0x1234...abcd",
  chain: "base"
)

Architecture

mcp-contract-auditor/
├── src/
│   ├── index.ts                    # MCP server entry (5 tools)
│   ├── types.ts                    # Type definitions
│   ├── tools/
│   │   ├── analyze-vulnerabilities.ts  # 15+ vuln detectors
│   │   ├── holder-analysis.ts      # Token holder analysis
│   │   └── generate-report.ts      # Markdown report generator
│   └── utils/
│       ├── blockscout.ts           # Blockscout API client
│       └── chains.ts               # EVM chain configs
├── package.json
└── tsconfig.json

How It Works

1. Fetch — Retrieves verified contract source code from Blockscout API
2. Analyze — Runs 15+ pattern-based vulnerability detectors on the source
3. Holder Check — Fetches token holder data and calculates Gini coefficient
4. Report — Generates a structured markdown audit report with severity ratings

Disclaimer

This is an automated static analysis tool. It uses pattern matching and heuristics — it is NOT a substitute for a professional manual security audit. Always conduct thorough manual review before deploying contracts with real funds.

License

MIT

---

Built with ❤️ for CyOps Arena × MiniMax M3 Hackathon