solidity-mcp

Solidity-native security analysis as an MCP server and CLI. Compiles your Foundry or Hardhat project, builds a resolved codebase model, constructs a call graph, tracks state access, discovers invariants, and runs security detectors — exposing all of it as 35 MCP tools an AI agent can query.

Where Slither, Mythril, and friends stop at "here are findings," this tool also exposes the underlying analysis layers (model, graph, state flow, invariants) so an agent can reason about your codebase the same way an auditor does.

Install

# Global install (CLI from anywhere):
npm install -g @pbuda/solidity-mcp

# No-install one-shot:
npx @pbuda/solidity-mcp analyze .

# Per-project devDependency:
npm install -D @pbuda/solidity-mcp

Quick start

# Run the full analysis pipeline and print findings + invariants:
solidity-mcp analyze .

# Skip test, mock, and script files:
solidity-mcp analyze . --no-tests

# Add custom path filters (repeatable):
solidity-mcp analyze . --no-tests --exclude old/ --exclude legacy/

# Force build tool (otherwise auto-detected from foundry.toml / hardhat.config.ts):
solidity-mcp analyze . --build-tool foundry

Use as an MCP server in Claude Code

Add to .claude/settings.json in your Solidity project:

{
  "mcpServers": {
    "solidity": {
      "command": "npx",
      "args": ["-y", "@pbuda/solidity-mcp", "serve", "."]
    }
  }
}

The agent then has direct access to 35 query tools spanning model navigation, call graph traversal, state-access tracking, invariants, and detector findings.

What it produces

For a real project (Foundry bridge contracts, ~110 contracts):

| Layer | Output | |-------|--------| | Model | contracts, functions, modifiers, state variables, inheritance, storage layout | | Graph | call graph with execution context, edge types (direct/dynamic/low-level), modifier invocations, proxy resolution (EIP-1967, Transparent, UUPS) | | State access | per-function read/write sets with mutation expressions and guards | | State flow | mutation maps, paired-deltas, SCCs, function effects, net effects | | Invariants | discovered patterns: access-control, ordering (CEI), range, monotonicity, paired-delta, aggregate | | Detectors | findings with confidence × impact, source locations, evidence |

Built-in detectors

• reentrancy-single-function — state writes after external calls
• reentrancy-cross-function — cross-function reentrancy via shared state
• unchecked-external-call — low-level calls without return-value check
• tx-origin-authentication — tx.origin used in auth guards
• unprotected-selfdestruct — selfdestruct without authorization
• uninitialized-storage-pointer — local storage refs without initialization

Custom detectors can be added via the TypeScript plugin API or a config-driven rule language.

Requirements

• Node.js >= 18
• A compilable Foundry (foundry.toml) or Hardhat (hardhat.config.ts) project
• For Foundry: --ast --extra-output storageLayout are auto-injected at forge build time (with a warning); no config changes required
• For Hardhat: storageLayout should be in outputSelection for full coverage, but the tool degrades gracefully without it

CLI

solidity-mcp <command> <project-dir> [options]

Commands:
  analyze <dir>      Run full pipeline and print findings + invariants
  serve <dir>        Start the MCP server on stdio
  <query> <dir>      Run a query command (find-contracts, get-callees, ...)

Options:
  --no-tests                     Exclude test, script, and mock files
  --exclude <pattern>            Exclude files containing <pattern> (repeatable)
  --build-tool <hardhat|foundry> Override auto-detection
  --timeout <ms>                 Compilation timeout

Run solidity-mcp --help for the full query command list.

API reference

See API.md for the full MCP tool catalogue (35 tools across 6 categories), finding format, and invariant types.

Status

Production pipeline; actively iterated. All 14 features in the original roadmap are complete, and the tool runs end-to-end on real-world Foundry and Hardhat projects (Galachain bridge contracts, Agni, lista-dao, etc.).

License

MIT. See LICENSE.