web3-solidity-audit-mcp

SKILL 36 — SOLIDITY AUDIT MCP: CLAUDE-NATIVE SMART CONTRACT SCANNER

> From: github.com/mariano-aguero/solidity-audit-mcp — MCP server plugging Slither + Aderyn + SWC patterns into Claude Code

> 10 tools. 19 built-in finding explainers. 86 SWC detectors. DeFi + Web3 preset detector packs. CI/CD ready.

---

WHAT IT IS

An MCP server that gives Claude Code direct access to Slither, Aderyn, Slang AST, SWC pattern matching, and a gas optimizer — all in one unified pipeline with auto-deduplication. Instead of context-switching between tools, you ask Claude to audit a contract and get a merged, severity-sorted report.

Stack:

External (install separately):
  Slither   → Trail of Bits, 90+ detectors, deep data flow
  Aderyn    → Cyfrin Rust-based, fast AST analysis
  Echidna   → Property fuzzer (optional)
  Halmos    → Symbolic execution (optional)

Built-in (no install):
  Slang     → Nomic Foundation AST parser, precise pattern matching
  SWC       → 86 detectors against Smart Contract Weakness Classification registry
  Gas       → Storage packing, loop, calldata optimizations

---

INSTALL & CONFIGURE

# Prerequisites
pip install slither-analyzer solc-select
solc-select install 0.8.20 && solc-select use 0.8.20
curl -L https://foundry.paradigm.xyz | bash && foundryup

# Aderyn (Rust)
cargo install aderyn
# or: curl -L https://raw.githubusercontent.com/Cyfrin/aderyn/dev/cyfrinup/install | bash

# MCP server
npm install -g solidity-audit-mcp
# or: npx solidity-audit-mcp

# Optional fuzzers
brew install echidna    # macOS
pip install halmos      # symbolic execution

Wire into Claude Code — add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "audit": {
      "command": "npx",
      "args": ["solidity-audit-mcp"]
    }
  }
}

Or project-level .mcp.json in repo root:

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

Docker (all tools pre-installed):

docker run -v $(pwd):/contracts solidity-audit-mcp audit /contracts/Token.sol

---

THE 10 MCP TOOLS

analyze_contract — Full Pipeline (Start Here)

analyze_contract(
  contractPath: "contracts/Vault.sol",
  analyzers: ["slither", "aderyn", "slang"],   # or omit for all
  runTests: true                                 # run forge tests too
)

Pipeline:

1. Parse metadata (functions, state vars, inheritance)
2. Run Slither + Aderyn in parallel
3. Detect risky patterns via Slang AST
4. Deduplicate findings across all tools
5. Sort by severity
6. Return unified report + JSON

get_contract_info — Attack Surface Map (No Analysis)

get_contract_info("contracts/Protocol.sol")

Returns instantly:

• Functions by visibility (external, public, internal, private)
• Payable functions — all ETH entry points
• delegatecall usage — proxy risk surface
• State variables and modifiers
• Inheritance chain

Use before full audit to understand the attack surface.

check_vulnerabilities — SWC Pattern Scan

check_vulnerabilities(
  contractPath: "contracts/Token.sol",
  detectors: ["SWC-107", "SWC-115", "CUSTOM-017"]  # or omit for all 86
)

19 built-in finding explainers (full Foundry PoC + remediation):

| ID | Finding | Severity |

|----|---------|---------|

| SWC-107 | Reentrancy | Critical |

| SWC-112 | Delegatecall to untrusted callee | Critical |

| CUSTOM-017 | Missing access control on critical function | Critical |

| CUSTOM-018 | ERC-7702 unprotected initializer | Critical |

| CUSTOM-004 | Price oracle manipulation / flash loan | Critical |

| CUSTOM-032 | ERC-4337 paymaster drain | Critical |

| SWC-101 | Integer overflow/underflow (unchecked) | High |

| SWC-104 | Unchecked call return value | High |

| SWC-115 | Authorization through tx.origin | High |

| CUSTOM-001 | Array length mismatch | High |

| CUSTOM-011 | Signature without replay protection | High |

| CUSTOM-029 | Merkle double-claim | High |

| SWC-116 | Block timestamp dependence | Medium |

| CUSTOM-005 | Missing zero address validation | Medium |

| CUSTOM-013 | Hash collision via abi.encodePacked | Medium |

| CUSTOM-015 | Division before multiplication | Medium |

| CUSTOM-016 | Permit without deadline | Medium |

| SWC-100 | Function default visibility | Medium |

| SWC-103 | Floating pragma | Low |

explain_finding — Deep Dive on Any Finding

explain_finding(
  findingId: "CUSTOM-011",         # or "SWC-107", or keyword "reentrancy"
  contractContext: "ERC4626 vault with harvest callback"
)

Returns: root cause → impact → step-by-step exploit → vulnerable code → secure code → Foundry PoC template → remediation → references.

Use this mid-hunt when you find a suspicious pattern and want the full exploit scenario before writing a PoC.

Supported keywords: reentrancy, overflow, flash loan, oracle, replay, nonce, encodepacked, precision loss, permit, access control, merkle, airdrop, erc-7702, paymaster, erc-4337, delegatecall, tx.origin, zero address, timestamp

generate_invariants — Auto-Generate Foundry Invariant Tests

generate_invariants(
  contractPath: "contracts/Vault.sol",
  protocolType: "vault"    # auto, erc20, erc721, vault, lending, amm, governance, staking
)

Returns ready-to-paste invariant_*() functions + handler contract + forge test --invariant run commands.

Protocol-specific invariants generated:

ERC-4626 vault:    totalAssets >= total share value
                   share price non-decreasing
                   deposit/withdraw round-trip solvency
Lending:           protocol solvency, liquidatable positions
AMM:               constant product k, no free lunch on swap
Staking:           reward monotonicity, total staked balance, slash accounting
Governance:        proposal state machine, quorum immutability

diff_audit — Audit Only Changes

diff_audit(
  oldContractPath: "v1/Vault.sol",
  newContractPath: "v2/Vault.sol",
  focusOnly: true   # only report issues in changed code
)

Returns: functions added/removed/modified, new vulns introduced, issues resolved. Use on upgrade PRs.

audit_project — Whole Directory

audit_project(
  projectRoot: "./contracts",
  exclude: ["node_modules/**", "test/**", "mocks/**"]
)

Aggregated findings across all .sol files + per-contract breakdown + project-level risk score.

optimize_gas — Gas Analysis

optimize_gas("contracts/Protocol.sol", includeInformational: true)

Returns: storage packing opportunities, loop optimizations, calldata vs memory, visibility suggestions, estimated savings per change.

run_tests — Forge Integration

run_tests(projectRoot: ".", contractName: "Vault")

Returns: pass/fail/skip counts, coverage %, gas report, execution time.

generate_report — Formatted Output

generate_report(findings, contractInfo, format: "markdown", projectName: "Protocol")

Formats into: executive summary + risk level + findings table + remediation guidance.

---

DeFi DETECTOR PRESET

The defi.json preset contains 10 high/medium severity DeFi-specific detectors:

oracle-manipulation      → HIGH  — spot price used, no TWAP, no staleness check
flash-loan-risk          → HIGH  — balance check before/after single tx
slippage-check           → HIGH  — swap with no minOut parameter
reentrancy-erc777        → HIGH  — ERC777 tokensReceived callback reentrancy
donation-attack          → HIGH  — totalAssets() uses balanceOf (inflatable)
price-stale-check        → HIGH  — Chainlink latestRoundData without check
unchecked-transfer       → MEDIUM — transfer/transferFrom return value ignored
precision-loss           → MEDIUM — division before multiplication
front-running-vulnerable → MEDIUM — state change in predictable order
liquidity-removal-risk   → MEDIUM — LP withdrawal without reserve check

Load in Claude Code:

analyze_contract("contracts/Vault.sol", analyzers: ["slither", "aderyn"], detectorPreset: "defi")

---

CI/CD — GITHUB ACTIONS WORKFLOW

Drop this in .github/workflows/audit.yml to block PRs with Critical/High findings:

name: Smart Contract Audit
on:
  pull_request:
    paths: ["**.sol"]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20" }
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }

      - name: Install tools
        run: |
          pip install slither-analyzer solc-select
          solc-select install 0.8.28 && solc-select use 0.8.28
          ADERYN_VER=$(curl -sf https://api.github.com/repos/Cyfrin/aderyn/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
          curl -fL "https://github.com/Cyfrin/aderyn/releases/download/${ADERYN_VER}/aderyn-x86_64-unknown-linux-gnu.tar.xz" | tar -xJf - -C /tmp
          sudo install -m 755 /tmp/aderyn /usr/local/bin/aderyn
          npm install -g solidity-audit-mcp

      - name: Audit changed contracts
        run: |
          # Get changed .sol files
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }} | grep '\.sol$' || true)
          for f in $CHANGED; do
            solidity-audit-cli audit "$f" --severity-threshold high --format sarif --output results.sarif
          done

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with: { sarif_file: results.sarif }

Exit codes for CI gates:

0 → no findings above threshold → PR can merge
1 → findings detected → block PR
2 → execution error → investigate

---

CLI USAGE (Outside Claude Code)

# Full audit
solidity-audit-cli audit ./contracts/Token.sol

# Filter severity
solidity-audit-cli audit ./contracts/Token.sol --severity-threshold high

# Different output formats
solidity-audit-cli audit ./contracts/Token.sol --format json
solidity-audit-cli audit ./contracts/Token.sol --format sarif --output results.sarif
solidity-audit-cli audit ./contracts/Token.sol --format markdown

# Compare versions
solidity-audit-cli diff ./v1/Token.sol ./v2/Token.sol

# Gas analysis
solidity-audit-cli gas ./contracts/Token.sol

---

SAAS / REMOTE MODE

Run as a remote MCP server that any client connects to via SSE:

# Start
MCP_API_KEY=your-secret npm run saas:up  # → http://localhost:3000

# Configure client
{
  "mcpServers": {
    "audit": {
      "transport": "sse",
      "url": "http://your-server:3000/sse",
      "headers": { "Authorization": "Bearer your-secret" }
    }
  }
}

# Health check
GET /health  → { "tools": 10, "slither": {"available": true}, "aderyn": {"available": true} }

---

ERN — SOLIDITY AUDIT MCP APPLIED

# STEP 1: Attack surface map before touching code
get_contract_info("contracts/ErnVault.sol")
→ lists: payable functions, delegatecall usage, external functions without modifiers

# STEP 2: Full pipeline with DeFi preset
analyze_contract(
  "contracts/ErnDistributor.sol",
  analyzers: ["slither", "aderyn", "slang"]
)
→ Slither will flag: DISTRIBUTOR_ROLE with no granted address
→ Aderyn will flag: unchecked return value in aToken.transfer()
→ SWC will flag: CUSTOM-017 missing access control on distributeRewards()

# STEP 3: Generate invariants for yield accounting
generate_invariants(
  "contracts/ErnVault.sol",
  protocolType: "vault"
)
→ Returns ready-to-paste Foundry invariant tests:
  invariant_totalAssetsGteDebt()        ← aToken balance >= totalDeposited
  invariant_sharePriceNonDecreasing()   ← cumulativeRewardPerShare only increases
  invariant_depositWithdrawRoundTrip()  ← user gets back what they put in

# STEP 4: Explain the signature replay finding in detail
explain_finding("CUSTOM-011", contractContext: "Ern distributor with off-chain signatures")
→ Returns: exploit scenario + vulnerable code + fixed code + Foundry PoC template

# STEP 5: Run invariant tests
run_tests(projectRoot: ".", contractName: "ErnVault")
→ Any invariant failure = confirmed Critical finding

---

→ NEXT: [00-START-HERE.md](00-START-HERE.md)