io.github.vschernoff/solhint-mcp

solhint-mcp

Lint and autofix Solidity smart contracts with Solhint, from any MCP client — Claude Code, OpenAI Codex, Cursor, Windsurf, Claude Desktop, and anything else that speaks the protocol. Nothing in it is specific to one vendor.

Your agent gets seven tools: lint_solidity, lint_file, lint_project, fix_solidity, fix_file, explain_rule and get_config.

Solhint's CLI points users at this package — protofire/solhint#801, shipped in Solhint 6.2.5.

Installation

Add this to your MCP client's configuration, with the Solidity project as the working directory:

{
  "mcpServers": {
    "solhint": {
      "command": "npx",
      "args": ["-y", "solhint-mcp"]
    }
  }
}

Requires Node.js 20 or newer. On native Windows, a client that cannot start the server may need "command": "cmd" with "args": ["/c", "npx", "-y", "solhint-mcp"]: Node cannot spawn npx.cmd directly without a shell.

One server process lints one project: its working directory is the project root, so start another process for a different project. A Solhint installed in that project takes precedence over the copy bundled here.

How it runs Solhint

The server calls Solhint through its JavaScript API. It does not start a shell, invoke npx solhint, make update checks, or parse CLI output.

Client-specific shortcuts

Claude Code — from the Solidity project directory:

claude mcp add solhint -- npx -y solhint-mcp

The default local scope associates the server with the current project. Use --scope project before -- if the configuration should be committed in .mcp.json. On native Windows, if the server fails to start, wrapping npx in cmd /c is the usual fix — Node cannot spawn npx.cmd directly without a shell:

claude mcp add solhint -- cmd /c npx -y solhint-mcp

OpenAI Codex — Codex uses TOML, not the JSON block above, and shares one configuration across the Codex CLI, the ChatGPT desktop app and the IDE extension. From the Solidity project directory:

codex mcp add solhint -- npx -y solhint-mcp

Or add it by hand to ~/.codex/config.toml, or to .codex/config.toml to scope it to one project:

[mcp_servers.solhint]
command = "npx"
args = ["-y", "solhint-mcp"]

Cursor / Windsurf — add the JSON block above to the editor's MCP settings.

Claude Desktop — installation is separate from Claude Code. This package is a stdio npm server, not a packaged Desktop Extension (.mcpb). Configure it as a local development MCP server only if the client launches it with the Solidity project as its working directory. See Anthropic's current local-server instructions.

Tools

lint_project autodetects contracts/**/*.sol, then src/**/*.sol, and finally **/*.sol. Paths and patterns outside the project root are rejected.

The optional config argument accepts rule maps and the built-in solhint:recommended and solhint:all presets. It does not accept an extends path, a shareable config package name, or plugins: Solhint loads those with require, so honouring them from a tool argument would let anything able to call the tool run code in the server process. Declare them in the project's own .solhint.json, which carries the same trust as running npx solhint in that directory.

Run health

Solhint reports a plugin it cannot load, or a rule id it does not recognise, as a warning and then lints anyway — checking less than the project asked for. A tool result that showed only the findings would be read as a clean pass over a broken config.

Those warnings are captured and reported above the findings instead:

⚠️ This run was degraded — Solhint checked less than the project asked for.
- Could not load solhint-plugin-foo, make sure it's installed and exports valid rules. Ignoring it.
- Rule 'no-such-rule' doesn't exist

Treat the result below as incomplete until this is fixed. A finding that is absent may
only mean the rule never ran.

get_config provokes the same diagnostics with a throwaway lint, since Solhint only emits them when it loads rules, and get_config is where someone looks to find out whether the config is sound.

The fix_* tools apply Solhint's own autofixes and then re-lint, so what they report as remaining is what is genuinely left rather than the pre-fix report. fix_solidity returns the corrected source and touches nothing on disk. fix_file previews by default and only writes when called with write: true — Solhint's CLI asks for a backup before --fix, and an MCP client should not rewrite someone's contracts without being asked either.

explain_rule reads the documentation Solhint ships with each rule, so it covers the whole registry and always describes the version this project runs: description, category, default severity, configurable options, notes and the good/bad examples when the rule defines them.

If your repository already documents a lint command

An agent follows an explicit instruction in your repository over a tool description. If AGENTS.md, CLAUDE.md, .cursorrules or a similar agent playbook says how to lint, for example:

- Solidity lint: `npm run lint:sol`

the agent will run that command and never reach for these tools. That is reasonable behaviour, not a misconfiguration, but it means the server goes unused until you say it is there. Mention it alongside the command:

- Solidity lint: prefer the `solhint` MCP tools (`lint_file`, `lint_project`,
  `fix_file`, `explain_rule`, `get_config`) when that server is configured; they run this project's
  own Solhint with its config. Fall back to `npm run lint:sol` when the server is
  unavailable.

The two are complementary. The command is what a person and CI run. The tools are what an agent runs, and their advantage is that the invocation cannot drift: no unquoted ** collapsing to a single level, no forgotten config, no stray flag. A shell glob written by hand can silently cover a fraction of a project; lint_project cannot.

Configuration

lint_solidity uses configuration in this order:

1. The complete config object supplied to the tool.
2. The configuration found in the project root.
3. { "extends": "solhint:recommended" }.

An explicit config replaces the project config; it is not merged. File and project linting use Solhint's per-file configuration hierarchy and the same recommended fallback when no configuration exists.

The server prefers a compatible solhint (>=6.1.0 <7.0.0) installed by the project. If none exists, it uses its bundled, tested version. An installed but incompatible project version produces an explicit error. Pass --bundled-solhint only when you intentionally want the bundled version.

Solhint 6.0.x is excluded because its plugin loader can terminate the host process when a configured plugin cannot be loaded, which is unsafe for an in-process MCP server.

Protocol and current limitations

The server uses @modelcontextprotocol/server 2.x over stdio. It supports the current 2026-07-28 lifecycle and the SDK's legacy compatibility path.

Solhint currently resolves shareable configs and plugins relative to process.cwd(). That is why this release supports one project per process. A third-party plugin that writes to stdout synchronously is redirected to stderr while linting so it cannot corrupt the MCP channel. Full plugin isolation, cancellation, and lint timeouts are deferred to a worker-based release.

Docker

docker build -t solhint-mcp .
docker run -i --rm -v "$PWD":/project solhint-mcp

The server lints whatever directory it starts in, so the Solidity project is mounted at /project, which is the image's working directory. -i is required because the server speaks MCP over stdio; no port is exposed. A Solhint installed in the mounted project takes precedence over the image's own copy.

MCP Registry

Listed as io.github.vschernoff/solhint-mcp. server.json in this repository is the registry manifest; its name must stay identical to mcpName in package.json, and both version fields must match the published npm version, or a registry publish is rejected.

Credits and licence

MIT. The linting runner, tool surface and test suite are Diego Bale's (@dbale-arg) implementation, used here with his agreement under MIT. See NOTICE for the file-level breakdown.

Solhint is maintained by Protofire. This package depends on it; it is not part of it.