Solidity Audit Mcp

Solidity Audit MCP

[](https://github.com/mariano-aguero/solidity-audit-mcp/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://claude.ai)

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 (forge, cast, anvil) — testing & coverage
• solc-select with common Solidity versions (0.8.28, 0.8.24, 0.8.20, and more)
• Halmos — symbolic execution (x86_64 only; ARM64 skipped gracefully)
• Echidna — property fuzzer (x86_64 only; ARM64 skipped gracefully)

Platform notes:

• All tools work on x86_64 (standard CI/CD environments)
• On ARM64 (Apple Silicon), Slither, Aderyn, and Forge are fully available; Echidna and Halmos require x86_64

SaaS Mode (Remote Server)

Run the MCP server as a remote service that any MCP client can connect to via HTTP/SSE.

Quick Start

# Build and start the SaaS server
npm run saas:build
npm run saas:up

# Check status
curl http://localhost:3000/health

# View logs
npm run saas:logs

# Stop
npm run saas:down

Configuration

# 1. Copy example environment file
cp .env.example .env

# 2. Generate a secure API key
openssl rand -hex 32

# 3. Edit .env and set your API key
# MCP_API_KEY=your-generated-key

# 4. Start the server
npm run saas:up

Or set the API key inline:

MCP_API_KEY=your-secret-key npm run saas:up

MCP Client Configuration (SSE Transport)

Configure your MCP client to connect to the remote server:

{
  "mcpServers": {
    "audit": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:3000/sse"
      }
    }
  }
}

With API key authentication:

{
  "mcpServers": {
    "audit": {
      "transport": {
        "type": "sse",
        "url": "http://your-server.com:3000/sse",
        "headers": {
          "X-API-Key": "your-secret-key"
        }
      }
    }
  }
}

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Full health check with analyzer status | | /health/quick | GET | Quick health check (no analyzer verification) | | /info | GET | Server info and available tools | | /sse | GET | SSE connection for MCP | | /message | POST | Message handler for MCP | | /api/analyze | POST | Analyze contract from source code | | /api/check | POST | Quick vulnerability check from source | | /api/ci/review | POST | CI: Analyze & post inline PR comments |

Health Check Response

{
  "status": "healthy",
  "server": "solidity-audit-mcp",
  "version": "1.6.0",
  "uptime": 3600,
  "tools": 10,
  "analyzers": {
    "slither":  { "available": true,  "version": "0.11.5" },
    "aderyn":   { "available": true,  "version": "0.6.8" },
    "forge":    { "available": true,  "version": "1.5.1-stable" },
    "solc":     { "available": true,  "version": "0.8.28" },
    "echidna":  { "available": false, "error": "..." },
    "halmos":   { "available": false, "error": "..." },
    "slang":    { "available": true,  "version": "available" }
  },
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Status values:

• healthy — Core analyzers (Slither + Forge) available
• degraded — Only one core analyzer available, or only Slang (built-in)
• unhealthy — No analyzers available (returns HTTP 503)

> Note: echidna and halmos are opt-in fuzzers that require explicit setup. Their absence does not affect the overall status.

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Server port | | HOST | 0.0.0.0 | Server host | | MCP_API_KEY | (none) | API key for authentication (recommended for production) | | MCP_AUDIT_LOG_LEVEL | info | Log level (debug, info, warn, error) | | NODE_ENV | production | Node environment |

Authentication methods supported:

• Header: X-API-Key: your-key
• Bearer: Authorization: Bearer your-key

Production Deployment

For production, consider:

1. Use HTTPS - Put behind a reverse proxy (nginx) with SSL
2. Enable authentication - Set MCP_API_KEY
3. Mount contracts - Mount your contracts directory into the container
4. Resource limits - Set memory/CPU limits in docker-compose

Example with nginx SSL:

docker-compose -f docker/docker-compose.saas.yml --profile with-ssl up -d

Configuration

Option 1: Project-level configuration (.mcp.json)

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "a

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mariano-aguero](https://github.com/mariano-aguero)
- **Source:** [mariano-aguero/solidity-audit-mcp](https://github.com/mariano-aguero/solidity-audit-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.