Solhint Mcp

solhint-mcp

An MCP server that exposes Solhint as tools for 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.

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

Solhint's maintainer merged a change pointing Solhint's CLI at this package (protofire/solhint#801). It ships in the next Solhint release.

Requirements

• Node.js 20 or newer.
• One server process per Solidity project.

The process working directory is the project root. Start another server process for a different project.

Installation

Most clients are configured with a JSON block. Add this to your client's MCP configuration, with the Solidity project as the working directory:

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

On native Windows, clients that launch servers through npx generally need "command": "cmd" with "args": ["/c", "npx", "-y", "solhint-mcp"].

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, Claude Code requires cmd /c:

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 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 were originally written by Diego Bale (@dbale-arg) for protofire/solhint and moved here with his agreement, so the MCP server can be maintained and released independently of Solhint's release cycle. See NOTICE for the file-level breakdown.

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