io.github.vschernoffPublished by GitHub account vschernoffv0.1.0Updated Oct 29, 2026
Runs Foundry tests and builds; returns compact, structured failures to AI coding agents
Runs Foundry's forge test and forge build for an AI coding agent and returns compact, structured failures with reasons, traces and fuzz counterexamples.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
An MCP server that runs Foundry's forge test and forge build and returns compact,
structured results an AI coding agent can act on: for every failing test, its kind, the
decoded reason, the fuzz counterexample or invariant call sequence, console logs and a short
decoded trace. It speaks standard MCP over stdio and is meant for any MCP client (Claude Code,
Codex, Cursor, Claude Desktop, Windsurf, …). So far it has been tested with an MCP test client,
not yet inside each of those clients.
When forge did not run the tests (a compile error, no matching tests, a timeout, a missing
or unsupported forge, …) the tool says so as an error. It never reports "0 failed" for tests
that did not run.
Status: 0.1.0, the first release. See CHANGELOG.md for what is in it and what is not yet verified.
forge test executes the project's Solidity with your user's
rights. Use this server only on projects you would test in a terminal yourself.--allow-ffi, even when foundry.toml
enables it. forge runs with --offline, but tests can still reach the network themselves,
for example through fork cheatcodes.Details in Security and trust.
forge 1.8.5 or a later 1.8.x. You install it; this
server never installs or updates anything. Newer versions run but are flagged as untested.forge build in a terminal first. The
server runs forge with --offline, so it cannot download solc itself.Start the server in your Foundry project (the directory with foundry.toml, or below it).
Most clients accept this mcpServers entry:
Pin an exact version, as above. Client shortcuts, from each vendor's documentation (checked 2026-10-23, not yet verified by running each client):
Claude Code: put the JSON above in .mcp.json at the project root. In interactive sessions
Claude Code asks you to approve project servers the first time.
Cursor: put it in .cursor/mcp.json, adding "type": "stdio" to the server entry.
Codex: in .codex/config.toml (loaded for trusted projects only) or ~/.codex/config.toml:
The image contains the server and forge 1.8.6, the official static Alpine build. The build
checks the download against pinned SHA-256 digests; those digests were taken from the release's
provenance attestation and verified when they were pinned. Mount the project at /project
and a cache volume at /cache, where forge keeps the compiler:
The second command installs the project's solc once, online. Then configure the client to run
docker with ["run", "-i", "--rm", "-v", "<project>:/project", "-v", "forge-test-mcp-cache:/cache", "forge-test-mcp"]. forge writes out/ and cache/ into the
project, so on Linux add --user "$(id -u):$(id -g)" to both commands.
Options go after the package name in args. Only the user sets them; no tool argument can.
None of them sends transactions, deploys, signs or accepts keys.
A failing run_tests result looks like this:
Responses stay within the size budget. When there is more than fits, traces and logs go
first, then whole failures, and truncated says exactly how many were left out.
The result is an MCP error (isError: true) with a code, a message and a hint:
.env
contents, RPC URLs with API keys, or code you can't share.Running tests runs code. forge test executes the project's Solidity and cheatcodes with
your user's rights, just as it does in a terminal. Only use this server on projects you would
test in a terminal yourself. It cannot make an untrusted repository safe.
What the server does to reduce that risk:
FOUNDRY_FFI in the environment, so when foundry.toml sets ffi = true the server runs
forge with a copy of the resolved configuration that has ffi = false, and checks through
forge that it took effect before running anything. Start the server with --allow-ffi if
you want FFI.--offline, so forge itself makes no network
lookups. Tests can still reach the network on their own, for example fork tests through
vm.createSelectFork and RPC endpoints.--flag=value arguments..env itself, so tests can read and print those
values. The server replaces the exact values of variables named like *PRIVATE_KEY*,
*MNEMONIC*, *SECRET*, *TOKEN*, *API_KEY* and *RPC_URL* (RPC URLs often embed an API
key), from its environment and .env, with
[redacted:NAME]. A hex value such as a private key is also caught without 0x, in either
case, without leading zeros, and in decimal (as vm.envUint and console.log print it). It
cannot catch a secret printed in any other form. Keep spendable keys out of projects you
test with an agent.To report a vulnerability, see SECURITY.md.
Passing tests do not prove a contract is secure. They show the tests you wrote pass. Contracts that will hold value need an independent audit.
Tested in CI against forge 1.8.5 and 1.8.6 on Linux, macOS and Windows. Supported range:
>=1.8.5 <1.9.0. Older versions are refused. Newer ones run with a forgeUntested note
(or are refused with --strict-version).
npm test runs the unit tests. With FORGE_BIN=/path/to/forge it also runs the integration
tests against a real forge. npm run lint checks style. Requirement IDs in code and tests
(FR-, NFR-, D-) refer to the project's internal specification.
MIT © Vitaliy Chernov. See NOTICE for the licences of the dependencies.
Source: README.md at commit aa4f6e3
Run `forge test` and return a compact summary: counts, and for each failing test its kind (unit, fuzz, invariant, setup), decoded reason, fuzz counterexample or invariant call sequence, and console logs. isError means the tests did not run (compile error, no matching tests, timeout, missing forge, …); never report that as passing.
tracesfuzz_runsmax_bytesmatch_pathmatch_testmatch_contractRe-run one test at high verbosity and return only that test: its reason, decoded call trace (trimmed to the path to the revert when long), backtrace, logs and, for fuzz or invariant tests, the counterexample. Pass the test name as run_tests reports it, e.g. "BankTest.test_transfer()".
testrequiredcontractmax_bytesCompile the project with `forge build` and return compiler errors and warnings as structured items (file, line, column, code, message). Unchanged files are not recompiled and forge does not repeat their warnings; pass force: true to recompile everything.
forcemax_bytes90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
{ "mcpServers": { "forge-test": { "command": "npx", "args": ["-y", "[email protected]"] } }}[mcp_servers.forge-test]command = "npx"args = ["-y", "[email protected]"]docker build -t forge-test-mcp .docker run --rm -v "$PWD":/project -v forge-test-mcp-cache:/cache --entrypoint forge forge-test-mcp build{ "status": "failed", "forge": "1.8.6", "summary": { "suites": 1, "passed": 1, "failed": 1, "skipped": 0 }, "ffi": "disabled", "fuzzRuns": { "configured": 256, "used": 256 }, "notRun": [], "failures": [ { "test": "SupplyInvariantTest.invariant_supplyMatches()", "file": "test/Supply.t.sol", "kind": "invariant", "reason": "supply mismatch: 6683 != 6355", "sequence": { "calls": [ { "call": "Handler.mint(uint256)", "args": "6683", "sender": "0x…022f" }, { "call": "Handler.burnFrom(uint256)", "args": "328", "sender": "0x…054e" } ], "shrunkFrom": 4 }, "trace": [ "[21670] SupplyInvariantTest::invariant_supplyMatches()", " ├─ [0] VM::assertEq(6683, 6355, \"supply mismatch\") [staticcall]", " │ └─ ← [Revert] supply mismatch: 6683 != 6355", " └─ ← [Revert] supply mismatch: 6683 != 6355" ], "traceLinesOmitted": 16 } ], "truncated": null}