contractscan-mcp 0.1.0

ContractScan MCP Server — multi-engine Solidity vulnerability scanner for LLM agents

ContractScan MCP Server

Expose ContractScan's multi-engine Solidity vulnerability scanner as a Model Context Protocol (MCP) server. Once connected, any MCP-compatible AI tool (Claude Desktop, Cursor, Windsurf, Cline, …) can scan smart contracts directly from a conversation.

Why MCP?

Tool	Engines
Slither-MCP	Slither only
Aderyn-MCP	Aderyn only
ContractScan MCP	Slither + Semgrep + Mythril + AI cross-verification

Requirements

• Python 3.11+
• pip install contractscan-mcp
• solc installed (solc-select install 0.8.20 && solc-select use 0.8.20)

Quick Start

Install

pip install contractscan-mcp

Test it works

contractscan-mcp --help

---

IDE Setup

Claude Desktop (macOS / Windows)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}

Restart Claude Desktop. You should see ContractScan in the MCP tools list.

---

Cursor

Open Cursor Settings → MCP (or edit ~/.cursor/mcp.json):

{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}

Restart Cursor. ContractScan tools will appear in the Composer context.

---

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}

Restart Windsurf. ContractScan will be available in Cascade.

---

Cline (VS Code)

In VS Code, open Cline settings and add to MCP Servers:

{
  "contractscan": {
    "command": "contractscan-mcp",
    "env": {
      "ANTHROPIC_API_KEY": "sk-ant-..."
    }
  }
}

---

Claude Code (CLI)

Add to your project's CLAUDE.md:

## MCP Tools

This project uses ContractScan MCP for smart contract security scanning.

Install: `pip install contractscan-mcp`

Add to `~/.claude/settings.json`:
\`\`\`json
{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": { "ANTHROPIC_API_KEY": "YOUR_KEY" }
    }
  }
}
\`\`\`

Or run directly from the Claude Code terminal:

# Scan a single file
echo '{"tool":"scan_file","args":{"file_path":"contracts/Token.sol"}}' \
  | contractscan-mcp

# Or use Claude Code with MCP enabled (add to settings.json first)

---

Available Tools

scan_contract

Scan Solidity source code passed as a string.

Parameter	Type	Default	Description
solidity_code	string	required	Full Solidity source
filename	string	"contract.sol"	Filename shown in reports
generate_report	bool	true	Generate AI narrative report
anthropic_api_key	string	env ANTHROPIC_API_KEY	BYOK Anthropic key
openai_api_key	string	env OPENAI_API_KEY	BYOK OpenAI key
tier	string	"free"	"free" / "basic" / "pro"

scan_file

Scan a local .sol file or directory of Solidity files.

Parameter	Type	Default	Description
file_path	string	required	Absolute or relative path
generate_report	bool	true	Generate AI narrative report
anthropic_api_key	string	env ANTHROPIC_API_KEY	BYOK Anthropic key
openai_api_key	string	env OPENAI_API_KEY	BYOK OpenAI key
tier	string	"free"	"free" / "basic" / "pro"

get_engines

List all registered scan engines and their availability.

{
  "engines": [
    {"name": "slither",  "tier": "free",  "available": true},
    {"name": "mythril",  "tier": "basic", "available": true},
    {"name": "semgrep",  "tier": "basic", "available": true},
    {"name": "ai",       "tier": "free",  "available": true}
  ]
}

get_report

Retrieve the most recent scan result from the current session.

---

Analysis Tiers

Tier	Engines included
free	Slither + AI
basic	Slither + Semgrep + Mythril + AI
pro	All engines

---

API Keys

The server reads API keys from environment variables or from the tool call arguments (BYOK):

Variable	Use
ANTHROPIC_API_KEY	Claude-based AI report / detection
GOOGLE_API_KEY	Gemini-based AI report / detection
OPENAI_API_KEY	GPT-4o-based AI report / detection

At least one AI key is recommended for full reports. Static analysis (Slither / Semgrep / Mythril) works without any key.

---

Example Usage (in Claude Desktop)

Once connected, you can use ContractScan in natural language:

"Scan this contract for vulnerabilities" — paste your Solidity code

"Check /path/to/contracts/Token.sol for security issues" — scan a local file

"What engines are available?" — list configured engines

---

Impact on Existing Features

The MCP server runs as a separate process using stdio transport. It does not modify or affect the existing ContractScan web API or FastAPI application.