forge-test-mcp
This MCP server runs Foundry forge test and forge build and returns compact, structured results for AI coding agents.
Run
forge testwith optional filters (match_test,match_contract,match_path), fuzz-run override, trace toggle, and response-size budget; get counts and structured failure details (kind, reason, fuzz counterexample or invariant call sequence, logs, decoded trace).Re-run one failing test at high verbosity with
explain_failure, returning only that test’s reason, trace/backtrace, logs, and counterexample where applicable.Run
forge buildand get compiler errors and warnings as structured items with file, line, column, code, and message; optionally force a full recompile.Distinguish “tests did not run” from passing by returning MCP errors with codes for compile failure, no matching tests, timeout, missing forge, etc.
Safely run only test/build operations: no transactions, deploys, signing, or key handling; FFI is off unless explicitly enabled, and forge runs offline.
Runs Foundry's forge test and forge build for Solidity projects, returning structured test results such as failing test kinds, decoded reasons, fuzz counterexamples, invariant call sequences, console logs, decoded traces, and compiler errors/warnings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@forge-test-mcp run my Foundry tests and explain why the failing ones fail"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
forge-test-mcp
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.
Before you use it
Running tests runs code.
forge testexecutes the project's Solidity with your user's rights. Use this server only on projects you would test in a terminal yourself.FFI is off unless you start the server with
--allow-ffi, even whenfoundry.tomlenables it. forge runs with--offline, but tests can still reach the network themselves, for example through fork cheatcodes.No transactions. No tool sends transactions, deploys, signs or takes a key.
Passing tests do not prove a contract is secure.
Details in Security and trust.
Related MCP server: TestHeal
Requirements
Node.js 22 or later.
Foundry with
forge1.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.The project's compiler version installed once: run
forge buildin a terminal first. The server runs forge with--offline, so it cannot download solc itself.
Configure your MCP client
Start the server in your Foundry project (the directory with foundry.toml, or below it).
Most clients accept this mcpServers entry:
{
"mcpServers": {
"forge-test": {
"command": "npx",
"args": ["-y", "forge-test-mcp@0.1.0"]
}
}
}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.jsonat 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:[mcp_servers.forge-test] command = "npx" args = ["-y", "forge-test-mcp@0.1.0"]
Docker
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:
docker build -t forge-test-mcp .
docker run --rm -v "$PWD":/project -v forge-test-mcp-cache:/cache --entrypoint forge forge-test-mcp buildThe 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
Options go after the package name in args. Only the user sets them; no tool argument can.
Option | Meaning |
| Project directory (default: where the client starts the server). |
| The |
| Stop a forge run after this long (default 300). |
| Let tests use FFI cheatcodes when |
| Refuse forge versions newer than the tested range instead of flagging them. |
Tools
Tool | What it does |
| Runs |
| Re-runs one test at high verbosity and returns only that test: reason, counterexample, logs, backtrace and the decoded trace. Pass the name as |
| Runs |
None of them sends transactions, deploys, signs or accepts keys.
A failing run_tests result looks like this:
{
"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
}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.
When the tests did not run
The result is an MCP error (isError: true) with a code, a message and a hint:
Code | Cause |
| The project does not compile (the first compiler errors are included). |
| No test matched the filters, or every matched test was skipped. |
| No |
|
|
| Run |
| The run took longer than |
| forge could not produce a trustworthy report; the message and stderr say why. |
Report a problem or suggest an improvement
Problem or wrong result: open an issue. Include the version, your client, what was run and the output. Don't include keys,
.envcontents, RPC URLs with API keys, or code you can't share.Security problem: report it privately, see SECURITY.md.
You can ask your coding agent to draft the report from your session. Read it before you post it: nothing is sent unless you send it. This project collects no telemetry.
Security and trust
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:
FFI is off unless you opt in. FFI cheatcodes run arbitrary shell commands. forge ignores
FOUNDRY_FFIin the environment, so whenfoundry.tomlsetsffi = truethe server runs forge with a copy of the resolved configuration that hasffi = false, and checks through forge that it took effect before running anything. Start the server with--allow-ffiif you want FFI.No downloads. forge always runs with
--offline, so forge itself makes no network lookups. Tests can still reach the network on their own, for example fork tests throughvm.createSelectForkand RPC endpoints.No shell. forge is started with an argument list. Tool arguments are validated and passed as single
--flag=valuearguments.Secrets. forge loads the project's
.envitself, 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 without0x, in either case, without leading zeros, and in decimal (asvm.envUintandconsole.logprint it). It cannot catch a secret printed in any other form. Keep spendable keys out of projects you test with an agent.No transactions. No tool broadcasts, deploys, signs or takes a key.
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.
Foundry compatibility
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).
Development
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.
License
MIT © Vitaliy Chernov. See NOTICE for the licences of the dependencies.
Available Tools
3 toolsbuildA
Compile 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.
Inputs: force, max_bytes.
explain_failureA
Re-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()".
Inputs: test (required), contract, max_bytes.
run_testsA
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.
Inputs: traces, fuzz_runs, max_bytes, match_path, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
run_tests, explain_failure, and build have clearly distinct purposes: one runs the suite, one drills into a single failure at high verbosity, one compiles. An agent can easily route each request.
run_tests and explain_failure follow verb_noun, while build is a bare verb. Minor deviation but still readable and predictable.
Three tools is slightly thin but each earns its place covering the core workflow of build, run, and diagnose. Well-scoped for a focused Foundry testing server.
The build-run-explain lifecycle is fully covered, including structured compiler output and fuzz/invariant counterexamples. Minor gaps like listing tests or coverage exist but core workflows are complete.
Maintenance
Related MCP Connectors
Test analytics for AI agents: test history, flaky tests, failure clusters, coverage.
Change-aware CI validation and affected-test guidance for coding agents.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Find your AI agent's likely failure mode, get runtime settings, and clarify ambiguous prompts.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides structured, sandboxed test and lint feedback for coding agents, returning compact typed verdicts with failure fingerprints instead of raw runner output. It enables impact-selected test execution in isolated containers, distinguishing pre-existing failures from regressions.4Apache 2.0
- AlicenseAqualityCmaintenanceProvides AI coding agents with reliable root-cause diagnosis and minimal, high-confidence fixes for failing tests.31MIT
- AlicenseAqualityBmaintenanceEnables AI agents to run, debug, and inspect Playwright end-to-end tests, returning structured pass/fail stats, failure diagnostics with actionable fix hints, live DOM inspection, selector validation, visual diffs, and flakiness verdicts instead of raw test output.11MIT
- AlicenseAqualityBmaintenanceLints and autofixes Solidity smart contracts with Solhint, from any MCP client. Exposes lint_solidity, lint_file, lint_project, fix_solidity, fix_file, explain_rule and get_config, running Solhint through its JavaScript API against the project's own config and installed version.7995 npm1MIT