# Solidity Audit Mcp

> Model Context Protocol (MCP) server that enables Claude to perform comprehensive security audits on Solidity smart contracts using Slither, Aderyn, and built-in pattern detection

- **Type:** MCP server
- **Install:** `agentstack add mcp-mariano-aguero-solidity-audit-mcp`
- **Verified:** Pending review
- **Seller:** [mariano-aguero](https://agentstack.voostack.com/s/mariano-aguero)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mariano-aguero](https://github.com/mariano-aguero)
- **Source:** https://github.com/mariano-aguero/solidity-audit-mcp

## Install

```sh
agentstack add mcp-mariano-aguero-solidity-audit-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```yaml
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:**

```solidity
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`:

```yaml
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+

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

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

### Slither

Static analysis framework by Trail of Bits.

```bash
# 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.

```bash
# 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).

```bash
# 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.

```bash
# 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):**

```bash
# 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.

```bash
# 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

```bash
# 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:

```bash
# 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

```json
{
  "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

```bash
# 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

```bash
# 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:

```bash
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:

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

With API key authentication:

```json
{
  "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

```json
{
  "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:

```bash
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:

```bash
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:

```json
{
  "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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mariano-aguero-solidity-audit-mcp
- Seller: https://agentstack.voostack.com/s/mariano-aguero
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.