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.origin misuse, 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, calldata vs memory usage, immutable/constant opportunities, 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.
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.
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: zk-circuit-auditor-mcp
solidity-auditor-mcp is a self-contained MCP server that:
Calls the Cysic Minimax model (minimax-m3) at
https://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.
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?) — runs
audit_contract and returns { format: "markdown", markdown, structured }.
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.
Node.js >= 18.0.0 (uses built-in fetch).
A CYSIC_API_KEY from the Cysic token-ai dashboard.
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.
# 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.
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. |
~/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"
}
}
}
}{
"mcpServers": {
"solidity-auditor": {
"command": "node",
"args": ["/absolute/path/to/solidity-auditor-mcp/server.js"],
"env": {
"CYSIC_API_KEY": "sk-your-cysic-key"
}
}
}
}Any client that speaks MCP-over-stdio works. Launch with node server.js
and pass CYSIC_API_KEY via the environment.
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.
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)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.
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.
MIT.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The full Solidity source code to audit. Pastes, file dumps, and multi-contract files are all accepted. | |
| contractName | No | Optional contract name. When omitted, the auditor infers it from `contract X { ... }`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It transparently describes the multi-pass process and specifies return values (severity, SWC id, etc., risk score 0-100, summary). No mention of side effects or destructive behavior, but the tool is read-only by nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: process, outputs, usage. Front-loaded with key information, no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and moderate complexity, it covers the audit process and outputs well. Minor gaps: no mention of runtime, limits, or error handling, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage on both parameters, and description adds practical context: source accepts pastes, file dumps, multi-contract files; contractName inferred when omitted. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool performs a 3-pass audit of a Solidity source file (recon, deep scan, severity scoring) and returns structured findings plus risk score. This distinguishes it from siblings like check_vulnerability (single check), gas_optimization, and generate_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this as the default entry point when reviewing a contract,' providing clear guidance on when to use this tool. Lacks explicit when-not or alternatives, but the strong recommendation suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The full Solidity source code to check. | |
| vulnClass | Yes | The vulnerability class to check for, e.g. 'reentrancy', 'integer-overflow', 'access-control'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Lists return fields (vulnerability status, severity, SWC id, fix recommendation) but does not disclose if it reads state, requires authentication, or handles errors. With no annotations, the description carries the burden but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first defines purpose and output, second gives usage recommendation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple check tool with 2 parameters, 100% schema coverage, and no output schema. Lacks error handling info but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters. Description adds value by giving concrete examples of vulnClass values and labeling source as Solidity code, beyond schema metadata.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'targeted check for a single vulnerability class' and provides specific examples (reentrancy, integer-overflow, etc.), distinguishing it from sibling tools like audit_contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends use for 'quick spot-checks during development', implying it is not for comprehensive audits. Context with sibling tools reinforces differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The full Solidity source code to review for gas savings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully bears the burden. It details the output (ordered list with estimated savings) and lists optimization types (storage packing, loop optimizations, etc.). This goes beyond basic purpose, though it doesn't mention side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the action and includes relevant details about the output. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the main functionality and output characteristics. It could mention output format or version constraints, but it is still fairly complete and distinct from sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'source', so baseline is 3. The description adds context by indicating the source is reviewed for gas savings and that the output is a list of suggestions, enhancing understanding of the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a gas optimization review of a Solidity source file and returns ordered suggestions. It is specific about the resource (Solidity source) and distinguishes from sibling tools like audit_contract (broader audit) and check_vulnerability (security).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for gas optimization but does not explicitly state when to use this tool over siblings or when not to use it. An agent can infer context from sibling names, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a full audit_contract and render the result as a clean Markdown report. Returns both the rendered Markdown and the underlying structured findings.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | The full Solidity source code to audit. | |
| contractName | No | Optional contract name. | |
| format | No | Currently only 'markdown' is supported. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool runs audit_contract (implying a computational step) and returns both Markdown and structured findings. However, it does not discuss potential side effects, rate limits, or performance implications of running the audit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that efficiently convey the action, input, and output. Every word is useful; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and no output schema, the description adequately explains the main purpose and return values. It mentions both rendered Markdown and structured findings, but omits details about the structure of those findings. Given the simplicity of the tool, this is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters already described in the schema. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a full audit_contract and renders the result as a clean Markdown report. It specifies both the action ('run and render') and the resource ('audit_contract result'), and distinguishes from siblings like audit_contract (which likely only runs the audit without rendering).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining a formatted report, but does not explicitly state when to use this tool versus alternatives like audit_contract or check_vulnerability. No when-not or alternative guidance is provided, though the purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0audit_contractcheck_vulnerabilitygas_optimizationgenerate_reportScored 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.
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.
Read-only smart-contract security intelligence for autonomous agents.
AI-powered threat intelligence, smart contract auditing, and cybersecurity OSINT.