Solhint MCP

What the solhint-mcp MCP server does

The solhint-mcp MCP server connects an MCP client to Solhint for Solidity linting, autofixing, rule documentation, and configuration inspection. It supports both in-memory source and files in the project directory, giving an agent separate operations for checking code, applying fixes, and understanding lint results.

The server belongs in the Developer Tools category and is intended for Solidity repositories where an agent needs to use the project's Solhint setup. It is a stdio npm server rather than a hosted service, so the client starts it locally with the Solidity project as its working directory.

How it works

The server calls Solhint through its JavaScript API instead of starting a shell, running the Solhint CLI, or parsing command output. A project-installed compatible Solhint version takes precedence over the bundled version. Supported project versions are >=6.1.0 <7.0.0; an incompatible installed version returns an error.

One process is associated with one project root. File paths and glob patterns outside that root are rejected. For project linting, the default search order is contracts/**/*.sol, then src/**/*.sol, and finally **/*.sol.

Source-string linting accepts an explicit complete configuration, otherwise it uses the project configuration or the recommended Solhint configuration. An explicit configuration replaces the project configuration rather than merging with it. File and project operations follow Solhint's per-file configuration behavior.

Setup and configuration

Configure the server as a local stdio process using npx -y solhint-mcp, with the Solidity repository as the working directory. Node.js 20 or newer is required. Native Windows clients that launch through npx generally need cmd /c npx -y solhint-mcp instead.

The same server can be run in Docker by mounting the repository at /project and keeping stdin attached. No network port is exposed because MCP communication uses stdio. A Solhint installation in the mounted project still takes precedence over the image copy.

Claude Code, OpenAI Codex, Cursor, Windsurf, and Claude Desktop are documented client choices. Claude Desktop must launch the package as a local development MCP server; it is not a packaged Desktop Extension.

Tools and capabilities

The solhint-mcp MCP server provides seven tools:

• lint_solidity checks a Solidity source string and can receive a configuration.
• lint_file checks one .sol file inside the project.
• lint_project checks files matching a project-relative glob.
• fix_solidity returns an autofixed source string without changing a file.
• fix_file previews an autofix by default and writes only when write: true is supplied.
• explain_rule returns the shipped documentation for a Solhint rule, including its category, default severity, options, notes, and available examples.
• get_config displays the project's Solhint configuration.

The fix operations apply Solhint's fixes and then lint again, so their remaining findings reflect the post-fix result.

Limitations and notes

The server does not provide full plugin isolation, cancellation, or lint timeouts. Plugins that synchronously write to stdout are redirected to stderr during linting so they do not corrupt the MCP channel. Solhint 6.0.x is excluded because its plugin loading can terminate the host process when a configured plugin cannot be loaded.

Repository instructions such as AGENTS.md, CLAUDE.md, or editor rules may tell an agent to use an existing lint command instead of MCP tools. In that situation, explicitly documenting the preferred Solhint MCP tools helps the agent select them. The package is MIT-licensed and depends on Solhint; it is maintained separately from Solhint itself.