solidity-auditor-mcp
This MCP server audits Solidity smart contracts using the Cysic Minimax AI model, providing four core capabilities:
audit_contract: Runs a comprehensive 3-pass audit (recon → deep vulnerability scan → severity scoring), returning structured findings with severity levels, SWC IDs, affected functions/lines, descriptions, fix recommendations, an overall risk score (0–100), and an executive summary.check_vulnerability: Performs a targeted check for a specific vulnerability class (e.g., reentrancy, integer overflow, access control,tx.originmisuse, unchecked external calls), returning vulnerability status, severity, SWC ID, and a fix recommendation.gas_optimization: Analyzes Solidity code for gas inefficiencies and returns an ordered list of actionable suggestions covering storage packing,calldatavsmemoryusage,immutable/constantopportunities, loop optimizations, short-circuit evaluation, and external call patterns — with estimated savings where possible.generate_report: Runs a full audit and produces a clean Markdown report (suitable for PR comments, docs, or ticketing systems), returning both the rendered Markdown and the underlying structured findings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@solidity-auditor-mcp Audit this contract and suggest gas improvements"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
solidity-auditor-mcp
An MCP (Model Context Protocol) server that audits Ethereum / Solidity
smart contracts using the Cysic Minimax model (minimax-m3).
It exposes four tools over stdio:
Tool | Purpose |
| Full 3-pass audit with SWC-tagged findings and a 0-100 risk score. |
| Targeted check for a single class (reentrancy, tx.origin, etc.). |
| Ordered, savings-estimated gas review. |
| Runs the full audit and returns a clean Markdown report. |
Drop it into Claude Desktop, Cursor, or any MCP client and ask "audit this contract" — the model handles the rest.
Problem statement
Manual smart-contract audits are slow and expensive. A serious audit of a single mid-sized protocol costs $50k-$200k and takes 3-6 weeks. Even DIY reviewers spend hours per contract on reconnaissance before they can start looking for real bugs. AI-assisted triage is a multiplier: a fast, calibrated first pass that surfaces the 5-20 most likely issues lets a human reviewer skip the recon and dive straight into validation.
Related MCP server: bug-bounty-intelligence-mcp
Solution
solidity-auditor-mcp is a self-contained MCP server that:
Calls the Cysic Minimax model (
minimax-m3) athttps://token-ai.cysic.xyz/v1/chat/completions(OpenAI-compatible).Runs a 3-pass audit pipeline (recon -> deep scan -> severity scoring) instead of a single prompt, which empirically reduces hallucinated function names and over-flagging.
Maps every finding to a SWC id (Smart Contract Weakness Classification) using a curated registry + category-alias table.
Handles large contracts by chunking at declaration boundaries before scanning.
Renders a clean Markdown report suitable for PR comments or ticketing systems.
Ships with defensive JSON parsing, retries on 5xx/429, strict input validation, and a
--help-friendly startup that never silently swallows errors.
Feature checklist
The exact tools shipped in this repository:
audit_contract(source, contractName?)— 3-pass audit returning{ findings: [{ severity, category, swcId, swcTitle, title, function, line, description, recommendation, confidence }], summary, executiveSummary, riskScore, meta }.check_vulnerability(source, vulnClass)— targeted check for one class (e.g.reentrancy,integer-overflow,access-control,tx.origin,unchecked-call). Returns{ isVulnerable, severity, swcId, ... }.gas_optimization(source)— ordered list of gas-saving suggestions with category (storage,memory,calldata,loop,external-call,immutable,constant,packing,short-circuit,other) and estimated savings.generate_report(source, contractName?, format?)— runsaudit_contractand returns{ format: "markdown", markdown, structured }.
Architecture overview
The runtime topology, module boundaries, and per-call data flow are
documented in detail in ARCHITECTURE.md. In
short:
MCP client
| JSON-RPC over stdio
v
server.js --(input validation, error wrapping)--> src/auditor.js
|
+-----------+-----------+
v v
src/prompts.js src/swc.js
(3 system+user (registry +
prompt templates) aliases)
|
v
src/cysicClient.js --HTTPS POST--> Cysic Minimax (minimax-m3)
(auth, timeout, retry, https://token-ai.cysic.xyz/v1
JSON repair)The 3-pass audit pipeline is the key innovation. Each pass has a narrow job:
Recon — summarize the contract map (state, functions, calls, value flows, assumptions). No vulnerability claims yet.
Deep scan — given the recon, list vulnerabilities with severity, SWC id, function, line, description, recommendation, confidence. Chunked for large sources.
Severity scoring — given the raw findings, recalibrate severity, merge duplicates, compute a 0-100 risk score, write a summary and an executive summary.
See ARCHITECTURE.md for the full rationale.
Setup & usage
Requirements
Node.js >= 18.0.0 (uses built-in
fetch).A
CYSIC_API_KEYfrom the Cysic token-ai dashboard.
Install
git clone <this-repo> solidity-auditor-mcp
cd solidity-auditor-mcp
npm install
cp .env.example .env
# then edit .env to set CYSIC_API_KEYOr skip the .env and pass the key through your MCP client config (see
below) — the server reads process.env.CYSIC_API_KEY only.
Run
# Locally, for smoke-testing
npm start
# Or directly
node server.jsThe server prints two lines to stderr and then listens on stdio.
Anything written to stdout is a JSON-RPC frame from the MCP SDK, so
never console.log from application code.
Environment variables
Variable | Required | Default | Notes |
| yes | (none) | Bearer token for the API. |
| no |
| Override for self-hosted/proxy. |
| no |
| Override for other Minimax models. |
| no |
| Per-request timeout in ms. |
Add to an MCP client
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows)
{
"mcpServers": {
"solidity-auditor": {
"command": "node",
"args": ["/absolute/path/to/solidity-auditor-mcp/server.js"],
"env": {
"CYSIC_API_KEY": "sk-your-cysic-key"
}
}
}
}Cursor (Settings -> MCP -> Add new global MCP server)
{
"mcpServers": {
"solidity-auditor": {
"command": "node",
"args": ["/absolute/path/to/solidity-auditor-mcp/server.js"],
"env": {
"CYSIC_API_KEY": "sk-your-cysic-key"
}
}
}
}Other MCP clients (Codex, OpenCode, custom agents)
Any client that speaks MCP-over-stdio works. Launch with node server.js
and pass CYSIC_API_KEY via the environment.
AI / Agent integration evidence
This server is a real, working integration with the Cysic Minimax
token-gated API. Every tool call results in one or more HTTPS POSTs to
https://token-ai.cysic.xyz/v1/chat/completions with
Authorization: Bearer $CYSIC_API_KEY and model: "minimax-m3". The
implementation lives in src/cysicClient.js
and is exercised by the orchestrator in
src/auditor.js.
A complete, expected tool-call transcript (with the response shape an
MCP client should see) is in examples/demo.md.
That document audits the deliberately broken
examples/Vulnerable.sol using all four
tools.
Project structure
solidity-auditor-mcp/
├─ server.js # MCP entry point (stdio transport, tool dispatch)
├─ package.json # CommonJS, only @modelcontextprotocol/sdk dep
├─ .env.example # Template for CYSIC_API_KEY and overrides
├─ README.md # This file
├─ ARCHITECTURE.md # 3-pass pipeline, module boundaries, data flow
├─ src/
│ ├─ cysicClient.js # OpenAI-compatible client for the Cysic Minimax API
│ ├─ auditor.js # Multi-pass audit orchestration
│ ├─ prompts.js # System + per-pass prompt templates
│ └─ swc.js # SWC registry + category-alias mapping
├─ examples/
│ ├─ Vulnerable.sol # Deliberately broken bank for demos
│ └─ demo.md # Expected tool-call transcript for all 4 tools
└─ docs/
├─ AGENTS.md # CyOps Planner->Builder->Reviewer build provenance
└─ plans/ # This run's Planner deliverable (build plan)Innovation
Three things in this project that are not just "wrap an LLM":
Multi-pass audit pipeline (recon -> deep scan -> severity scoring). Each pass has a narrow, well-defined job. Pass 1 builds a contract map; pass 2 hunts for bugs against that map; pass 3 re-scores severity and merges duplicates. This empirically reduces hallucinated function names and over-flagging compared to a single prompt and produces a more calibrated risk score.
SWC registry mapping. Every finding is tagged with a Smart Contract Weakness Classification ID via a curated registry + a category-alias table. This is what professional audit reports use, and it makes the findings ticketing-system-ready out of the box.
Large-contract handling. Sources over 80k characters are chunked at top-level declaration boundaries and scanned per chunk with a shared recon, capped at 6 chunks per audit. This keeps latency and cost predictable for big protocols.
How to verify
These steps reproduce the validation done at build time and exercise
both the syntax check and a single boot of the server. They do not
require a CYSIC_API_KEY (tool calls themselves will fail without one,
but boot and the JSON-RPC handshake do not).
# 1. All .js files parse with the Node syntax checker
for f in server.js src/cysicClient.js src/auditor.js src/prompts.js src/swc.js; do
node --check "$f" && echo "OK: $f"
done
# 2. Install the only runtime dep
npm install
# 3. Smoke-test the boot sequence (3s, then it is killed by `timeout`)
CYSIC_API_KEY=sk-stub timeout 3 node server.js
# Expected stderr:
# [solidity-auditor-mcp] starting (stdio transport)
# [solidity-auditor-mcp] WARNING: CYSIC_API_KEY is not set. Tool calls will fail until it is provided.
# [solidity-auditor-mcp] ready.
# Exit code 124 (timeout-killed) is expected - the server stays up until
# the stdio transport is closed by the MCP client.
# 4. With a real key, end-to-end audit of the demo contract
export CYSIC_API_KEY=sk-your-real-key
node -e '
const { makeAuditor } = require("./src/auditor");
const fs = require("fs");
const src = fs.readFileSync("./examples/Vulnerable.sol", "utf8");
const aud = makeAuditor();
aud.auditContract(src, "NaiveBank")
.then(r => {
console.log("contract:", r.contractName, "riskScore:", r.riskScore);
for (const f of r.findings) {
console.log("-", f.severity.toUpperCase().padEnd(13),
f.swcId || "------",
f.title, "@", f.function || "n/a");
}
})
.catch(e => { console.error("audit failed:", e.message); process.exit(1); });
'Expected tool-call transcripts for all four tools are in
examples/demo.md.
License
MIT.
Available Tools
4 toolsaudit_contractA
Run a 3-pass (recon -> deep vulnerability scan -> severity scoring) audit of a Solidity source file. Returns structured findings (severity, SWC id, function, line, description, recommendation) plus an overall risk score (0-100) and a short summary. Use this as the default entry point when reviewing a contract.
Inputs: source (required), contractName.
check_vulnerabilityA
Targeted check for a single vulnerability class (e.g. 'reentrancy', 'integer-overflow', 'access-control', 'tx.origin', 'unchecked-call'). Returns whether the contract is vulnerable, the severity, an SWC id, and a fix recommendation. Use this for quick spot-checks during development.
Inputs: source (required), vulnClass (required).
gas_optimizationA
Run a gas optimization review of a Solidity source file. Returns a list of concrete, ordered gas-saving suggestions (storage packing, calldata vs memory, immutable/constant, loop optimizations, short-circuiting, etc.) with estimated savings where possible.
Inputs: source (required).
generate_reportA
Run a full audit_contract and render the result as a clean Markdown report. Returns both the rendered Markdown and the underlying structured findings.
Inputs: source (required), contractName, format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: full audit, single vulnerability check, gas optimization, and report generation. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (audit_contract, check_vulnerability, gas_optimization, generate_report).
4 tools is well-scoped for a specialized Solidity auditor, covering core workflows without being too few or too many.
The set covers main audit, targeted vulnerability checks, gas optimization, and report generation. Minor gaps like historical audit retrieval but functional coverage is strong.
Maintenance
Related MCP Connectors
EVM audit (Slither + source + security.txt + MCP-probe + wallet-exposure). 6 tools + /trace.
AI security scanner for Solidity + free CC0 dataset of Sherlock audit-competition acceptance rates.
Autonomous ERC-8183 Solidity Smart Contract Security Auditor & USDC Escrow on Base Mainnet.
Smart-contract security audits for EVM chains and DAML: quote, run and fetch reports.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables static security audit of Solidity smart contracts by analyzing source code or deployed bytecode for vulnerabilities, providing risk scores and detailed findings.1MIT
- AlicenseAqualityBmaintenanceAI-powered smart contract security analysis for AI agents and developers, enabling scanning of Solidity repos for vulnerabilities.3559 npm11MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to audit Solidity smart contracts for security vulnerabilities, fetch verified source code from block explorers, decode calldata, and estimate gas costs across major EVM networks.4MIT
- FlicenseNot gradedqualityBmaintenanceEnables users to perform static security audits on EVM Solidity contract code for critical flaws such as reentrancy state changes, unhandled external calls, unchecked delegatecall, and tx.origin authentication vulnerabilities, returning risk audit reports.7-