Solidity Audit MCP

A Model Context Protocol (MCP) server for automated security analysis of Solidity smart contracts. Integrates with industry-standard tools like Slither and Aderyn, plus built-in pattern matching against the SWC Registry.

Quick Start: Add Auditing to Your Project

Add automated security audits to any Solidity project in 2 minutes:

1. Copy the workflow to your project

Create .github/workflows/audit.yml in your Solidity project:

name: Smart Contract Audit

on:
  pull_request:
    paths: ["**.sol"]
  push:
    branches: [main]
    paths: ["**.sol"]

permissions:
  contents: read
  pull-requests: write
  security-events: write
  checks: write

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install audit tools
        run: |
          pip install slither-analyzer solc-select
          solc-select install 0.8.28 && solc-select use 0.8.28
          curl -L https://foundry.paradigm.xyz | bash
          ~/.foundry/bin/foundryup
          echo "$HOME/.foundry/bin" >> $GITHUB_PATH
          # Install Aderyn (x86_64 Linux)
          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: Run Audit
        run: |
          audit-cli audit contracts/ --format markdown
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2. That's it!

Every PR that touches .sol files will be automatically audited.

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                        YOUR PROJECT                                 │
│                  (e.g., smart-contract-audit-example)               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. You modify Token.sol and create a PR                            │
│                                                                     │
│  2. GitHub triggers the audit workflow                              │
│                                                                     │
│  3. MCP Audit Server runs ALL analyzers on changed .sol files       │
│     (Slither, Aderyn, Slang AST, SWC patterns, Gas optimizer,       │
│      Echidna & Halmos when opt-in test functions are present)        │
│                                                                     │
│  4. Results appear directly in your PR:                             │
│     ├── ✓ Inline annotations on problematic lines                   │
│     ├── ✓ Summary comment with all findings                         │
│     ├── ✓ Check status (pass/fail based on severity)                │
│     └── ✓ Security tab integration (SARIF)                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

What You See in the PR

Inline annotations on each vulnerable line:

function withdraw(uint256 amount) external {
    require(balances[msg.sender] >= amount);

    (bool success, ) = msg.sender.call{value: amount}("");
    // ▲ 🟠 HIGH: Reentrancy vulnerability
    // │  State change after external call allows reentrancy attack.
    // │  Recommendation: Use checks-effects-interactions pattern.
    // └─ Detector: slither

    require(success);
    balances[msg.sender] -= amount;  // ← State change should be BEFORE the call
}

PR comment with full report:

┌────────────────────────────────────────────────────────────┐
│  🔍 Smart Contract Audit Report                            │
│                                                            │
│  Risk Level: 🟠 HIGH                                       │
│  Findings: 0 critical, 2 high, 3 medium                    │
│  Gas Optimizations: 5 suggestions (~500 gas savings)       │
│                                                            │
│  ┌──────────┬─────────────────────┬─────────────┬───────┐  │
│  │ Severity │ Title               │ Location    │ Tool  │  │
│  ├──────────┼─────────────────────┼─────────────┼───────┤  │
│  │ HIGH     │ Reentrancy          │ Token.sol:45│slither│  │
│  │ HIGH     │ Unprotected withdraw│ Token.sol:32│aderyn │  │
│  │ MEDIUM   │ Floating pragma     │ Token.sol:1 │slang  │  │
│  └──────────┴─────────────────────┴─────────────┴───────┘  │
└────────────────────────────────────────────────────────────┘

Check status on the PR:

• 🔴 Failed - If critical or high severity findings exist
• 🟢 Passed - If no findings above your configured threshold

Optional: On-Demand Audits via Issues

Want to trigger audits by creating an issue or comment? Add .github/workflows/audit-on-demand.yml:

name: On-Demand Audit

on:
  issues:
    types: [opened]
  issue_comment:
    types: [created]

permissions:
  contents: read
  issues: write

jobs:
  audit:
    if: contains(github.event.issue.title, 'audit') || contains(github.event.comment.body, 'audit')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install tools
        run: |
          pip install slither-analyzer
          npm install -g solidity-audit-mcp

      - name: Run Audit
        id: audit
        run: |
          audit-cli audit contracts/ --format markdown > report.md

      - name: Post Report
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('report.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: report
            });

Now create an issue with "audit" in the title, and get a full security report as a comment.

---

What It Does

The Solidity Audit MCP provides AI assistants (like Claude) with the ability to perform comprehensive security audits on Solidity smart contracts. It combines multiple analysis approaches:

External Analyzers (require installation):

• Slither - Trail of Bits' static analysis framework with 90+ vulnerability detectors
• Aderyn - Cyfrin's Rust-based analyzer for fast, accurate detection
• Foundry - Run forge tests and get coverage reports
• Echidna (opt-in) - Trail of Bits' property-based fuzzer; activates when contracts contain echidna_* test functions (x86_64 only)
• Halmos (opt-in) - Symbolic execution engine; activates when contracts contain check_* test functions

Built-in Analysis (no external dependencies):

• Slang Parser - Nomic Foundation's Solidity parser (@nomicfoundation/slang) for precise AST-based vulnerability detection. Included as npm dependency.
• SWC Pattern Matching - Detection against the Smart Contract Weakness Classification registry (86 detectors)

Findings from multiple tools are automatically deduplicated and sorted by severity, giving you a unified view of potential issues.

Prerequisites

Node.js 20+

# Using nvm (recommended)
nvm install 20
nvm use 20

# Or download from https://nodejs.org/

Slither

Static analysis framework by Trail of Bits.

# Using pip (requires Python 3.8+)
pip install slither-analyzer

# Or using pipx for isolated installation
pipx install slither-analyzer

# Verify installation
slither --version

Note: Slither requires solc (Solidity compiler) to be installed.

Aderyn

Rust-based analyzer by Cyfrin.

# Using cargo (requires Rust)
cargo install aderyn

# Or using curl (Linux/macOS)
curl -L https://raw.githubusercontent.com/Cyfrin/aderyn/dev/cyfrinup/install | bash
cyfrinup

# Verify installation
aderyn --version

Foundry

Development toolkit for Ethereum (includes forge, cast, anvil).

# Install foundryup
curl -L https://foundry.paradigm.xyz | bash

# Then run foundryup to install forge, cast, anvil
foundryup

# Verify installation
forge --version

solc (Solidity Compiler)

Required by Slither for compilation.

# Using solc-select (recommended - allows multiple versions)
pip install solc-select
solc-select install 0.8.20
solc-select use 0.8.20

# Or on macOS with Homebrew
brew install solidity

# Or on Ubuntu/Debian
sudo add-apt-repository ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install solc

# Verify installation
solc --version

Echidna (optional — property fuzzer)

Property-based fuzzer by Trail of Bits. Only needed if your contracts define echidna_* test functions.

Pre-built binary (Linux x86_64 / macOS):

# macOS (via brew)
brew install echidna

# Linux x86_64 — download latest pre-built binary
ECHIDNA_VER=$(curl -sf https://api.github.com/repos/crytic/echidna/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
ECHIDNA_VER_CLEAN="${ECHIDNA_VER#v}"
curl -L "https://github.com/crytic/echidna/releases/download/${ECHIDNA_VER}/echidna-${ECHIDNA_VER_CLEAN}-x86_64-linux.tar.gz" -o /tmp/echidna.tar.gz
tar -xzf /tmp/echidna.tar.gz -C /tmp
sudo install -m 755 /tmp/echidna /usr/local/bin/echidna

# Verify installation
echidna --version

Note: No pre-built ARM64 (Apple Silicon) binary is available. On ARM64, Echidna is skipped gracefully — all other analyzers remain functional.

Halmos (optional — symbolic execution)

Symbolic execution engine by a16z. Only needed if your contracts define check_* test functions.

# Using pip (requires Python 3.8+)
pip install halmos

# Or using pipx
pipx install halmos

# Verify installation
halmos --version

Note: Halmos depends on z3-solver. On ARM64 (Apple Silicon), a pre-built wheel may not be available and compilation from source requires cmake and build-essential. If install fails, Halmos is skipped gracefully.

Installation

# Clone the repository
git clone https://github.com/mariano-aguero/solidity-audit-mcp.git
cd solidity-audit-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Verify the build
node dist/index.js
# Should output: [INFO] Starting solidity-audit-mcp v1.6.0
# Press Ctrl+C to exit

Docker

For a complete environment with all tools pre-installed, use Docker:

# Build the image
npm run docker:build

# Run MCP server
npm run docker:run

# Run CLI audit
npm run docker:cli -- analyze /contracts/MyContract.sol

# Interactive shell with all tools
npm run docker:shell

Docker with Claude Desktop

{
  "mcpServers": {
    "audit": {
      "command": "docker",
      "args": ["run", "-i", "-v", "/path/to/contracts:/contracts", "solidity-audit-mcp"]
    }
  }
}

What's Included

The Docker image includes:

• Node.js 20
• Slither (Python) — static analysis
• Aderyn v0.6.8 (Rust) — fast AST-based detection
• Foundry (fo