{"id":"b5724739-404c-4a6f-8749-22c6a9c02098","slug":"forge-test-mcp","kind":"mcp","name":"forge-test-mcp","summary":"MCP server that runs Foundry tests and returns compact, structured failures for AI coding agents","owner":"vschernoff","repoUrl":"https://github.com/vschernoff/forge-test-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-23T15:20:33.000Z","addedAt":"2026-10-26T17:28:29.618Z","logoUrl":"https://avatars.githubusercontent.com/u/38105183?u=7595d15190dd3aa051798afdccb90db218abf680&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T17:31:00.290Z","sample":false,"url":"https://conduits.dev/tools/forge-test-mcp","language":"JavaScript","transports":["stdio"],"install":{"npm":"forge-test-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# forge-test-mcp\n\nAn MCP server that runs Foundry's `forge test` and `forge build` and returns **compact,\nstructured results** an AI coding agent can act on: for every failing test, its kind, the\ndecoded reason, the fuzz counterexample or invariant call sequence, console logs and a short\ndecoded trace. It speaks standard MCP over stdio and is meant for any MCP client (Claude Code,\nCodex, Cursor, Claude Desktop, Windsurf, …). So far it has been tested with an MCP test client,\nnot yet inside each of those clients.\n\nWhen forge did **not** run the tests (a compile error, no matching tests, a timeout, a missing\nor unsupported `forge`, …) the tool says so as an error. It never reports \"0 failed\" for tests\nthat did not run.\n\n> **Status:** 0.1.0, the first release. See [CHANGELOG.md](CHANGELOG.md) for what is in it\n> and what is not yet verified.\n\n## Before you use it\n\n- **Running tests runs code.** `forge test` executes the project's Solidity with your user's\n  rights. Use this server only on projects you would test in a terminal yourself.\n- **FFI is off** unless you start the server with `--allow-ffi`, even when `foundry.toml`\n  enables it. forge runs with `--offline`, but tests can still reach the network themselves,\n  for example through fork cheatcodes.\n- **No transactions.** No tool sends transactions, deploys, signs or takes a key.\n- **Passing tests do not prove a contract is secure.**\n\nDetails in [Security and trust](#security-and-trust).\n\n## Requirements\n\n- Node.js 22 or later.\n- [Foundry](https://getfoundry.sh) with `forge` **1.8.5 or a later 1.8.x**. You install it; this\n  server never installs or updates anything. Newer versions run but are flagged as untested.\n- The project's compiler version installed once: run `forge build` in a terminal first. The\n  server runs forge with `--offline`, so it cannot download solc itself.\n\n## Configure your MCP client\n\nStart the server **in your Foundry project** (the directory with `foundry.toml`, or below it).\nMost clients accept this `mcpServers` entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"forge-test\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"forge-test-mcp@0.1.0\"]\n    }\n  }\n}\n```\n\nPin an exact version, as above. Client shortcuts, from each vendor's documentation (checked\n2026-10-23, not yet verified by running each client):\n\n- **Claude Code:** put the JSON above in `.mcp.json` at the project root. In interactive sessions\n  Claude Code asks you to approve project servers the first time.\n- **Cursor:** put it in `.cursor/mcp.json`, adding `\"type\": \"stdio\"` to the server entry.\n- **Codex:** in `.codex/config.toml` (loaded for trusted projects only) or `~/.codex/config.toml`:\n\n  ```toml\n  [mcp_servers.forge-test]\n  command = \"npx\"\n  args = [\"-y\", \"forge-test-mcp@0.1.0\"]\n  ```\n\n### Docker\n\nThe image contains the server and forge 1.8.6, the official static Alpine build. The build\nchecks the download against pinned SHA-256 digests; those digests were taken from the release's\nprovenance attestation and verified when they were pinned. Mount the project at `/project`\nand a cache volume at `/cache`, where forge keeps the compiler:\n\n```bash\ndocker build -t forge-test-mcp .\ndocker run --rm -v \"$PWD\":/project -v forge-test-mcp-cache:/cache --entrypoint forge forge-test-mcp build\n```\n\nThe second command installs the project's solc once, online. Then configure the client to run\n`docker` with `[\"run\", \"-i\", \"--rm\", \"-v\", \"<project>:/project\", \"-v\",\n\"forge-test-mcp-cache:/cache\", \"forge-test-mcp\"]`. forge writes `out/` and `cache/` into the\nproject, so on Linux add `--user \"$(id -u):$(id -g)\"` to both commands.\n\n### Options\n\nOptions go after the package name in `args`. Only the user sets them; no tool argument can.\n\n| Option                | Meaning                                                                                   |\n| --------------------- | ----------------------------------------------------------------------------------------- |\n| `--root <dir>`        | Project directory (default: where the client starts the server).                          |\n| `--forge <path>`      | The `forge` executable (default: `forge` on `PATH`).                                      |\n| `--timeout <seconds>` | Stop a forge run after this long (default 300).                                           |\n| `--allow-ffi`         | Let tests use FFI cheatcodes when `foundry.toml` enables them. Off by default; see below. |\n| `--strict-version`    | Refuse forge versions newer than the tested range instead of flagging them.               |\n\n## Tools\n\n| Tool              | What it does                                                                                                                                                                                             |\n| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `run_tests`       | Runs `forge test`. Filters: `match_test`, `match_contract`, `match_path`; `fuzz_runs`; `traces` (default true); `max_bytes` (default 8192).                                                              |\n| `explain_failure` | Re-runs one test at high verbosity and returns only that test: reason, counterexample, logs, backtrace and the decoded trace. Pass the name as `run_tests` prints it, e.g. `\"BankTest.test_transfer()\"`. |\n| `build`           | Runs `forge build` and returns compiler errors and warnings with file, line, column and code. `force: true` recompiles everything.                                                                       |\n\nNone of them sends transactions, deploys, signs or accepts keys.\n\nA failing `run_tests` result looks like this:\n\n```json\n{\n  \"status\": \"failed\",\n  \"forge\": \"1.8.6\",\n  \"summary\": { \"suites\": 1, \"passed\": 1, \"failed\": 1, \"skipped\": 0 },\n  \"ffi\": \"disabled\",\n  \"fuzzRuns\": { \"configured\": 256, \"used\": 256 },\n  \"notRun\": [],\n  \"failures\": [\n    {\n      \"test\": \"SupplyInvariantTest.invariant_supplyMatches()\",\n      \"file\": \"test/Supply.t.sol\",\n      \"kind\": \"invariant\",\n      \"reason\": \"supply mismatch: 6683 != 6355\",\n      \"sequence\": {\n        \"calls\": [\n          { \"call\": \"Handler.mint(uint256)\", \"args\": \"6683\", \"sender\": \"0x…022f\" },\n          { \"call\": \"Handler.burnFrom(uint256)\", \"args\": \"328\", \"sender\": \"0x…054e\" }\n        ],\n        \"shrunkFrom\": 4\n      },\n      \"trace\": [\n        \"[21670] SupplyInvariantTest::invariant_supplyMatches()\",\n        \"  ├─ [0] VM::assertEq(6683, 6355, \\\"supply mismatch\\\") [staticcall]\",\n        \"  │   └─ ← [Revert] supply mismatch: 6683 != 6355\",\n        \"  └─ ← [Revert] supply mismatch: 6683 != 6355\"\n      ],\n      \"traceLinesOmitted\": 16\n    }\n  ],\n  \"truncated\": null\n}\n```\n\nResponses stay within the size budget. When there is more than fits, traces and logs go\nfirst, then whole failures, and `truncated` says exactly how many were left out.\n\n### When the tests did not run\n\nThe result is an MCP error (`isError: true`) with a code, a message and a hint:\n\n| Code                                                                                                                                                         | Cause                                                                          |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |\n| `COMPILE_FAILED`                                                                                                                                             | The project does not compile (the first compiler errors are included).         |\n| `NO_TESTS_RAN`                                                                                                                                               | No test matched the filters, or every matched test was skipped.                |\n| `NOT_A_FOUNDRY_PROJECT`                                                                                                                                      | No `foundry.toml` here or above it in the repository.                          |\n| `FORGE_NOT_FOUND`, `UNSUPPORTED_FORGE_VERSION`                                                                                                               | `forge` is missing, or older than 1.8.5.                                       |\n| `SOLC_MISSING`                                                                                                                                               | Run `forge build` once in a terminal so forge can install the compiler.        |\n| `TIMEOUT`                                                                                                                                                    | The run took longer than `--timeout`; forge reports nothing until it finishes. |\n| `CONFIG_ERROR`, `INVALID_ARGUMENTS`, `FORGE_CRASHED`, `FORGE_FAILED`, `UNPARSEABLE_OUTPUT`, `INCONSISTENT_RESULT`, `OUTPUT_TOO_LARGE`, `FFI_OVERRIDE_FAILED` | forge could not produce a trustworthy report; the message and stderr say why.  |\n\n## Security and trust\n\n**Running tests runs code.** `forge test` executes the project's Solidity and cheatcodes with\nyour user's rights, just as it does in a terminal. Only use this server on projects you would\ntest in a terminal yourself. It cannot make an untrusted repository safe.\n\nWhat the server does to reduce that risk:\n\n- **FFI is off unless you opt in.** FFI cheatcodes run arbitrary shell commands. forge ignores\n  `FOUNDRY_FFI` in the environment, so when `foundry.toml` sets `ffi = true` the server runs\n  forge with a copy of the resolved configuration that has `ffi = false`, and checks through\n  forge that it took effect before running anything. Start the server with `--allow-ffi` if\n  you want FFI.\n- **No downloads.** forge always runs with `--offline`, so forge itself makes no network\n  lookups. Tests can still reach the network on their own, for example fork tests through\n  `vm.createSelectFork` and RPC endpoints.\n- **No shell.** forge is started with an argument list. Tool arguments are validated and passed\n  as single `--flag=value` arguments.\n- **Secrets.** forge loads the project's `.env` itself, so tests can read and print those\n  values. The server replaces the exact values of variables named like `*PRIVATE_KEY*`,\n  `*MNEMONIC*`, `*SECRET*`, `*TOKEN*`, `*API_KEY*` and `*RPC_URL*` (RPC URLs often embed an API\n  key), from its environment and `.env`, with\n  `[redacted:NAME]`. A hex value such as a private key is also caught without `0x`, in either\n  case, without leading zeros, and in decimal (as `vm.envUint` and `console.log` print it). It\n  cannot catch a secret printed in any other form. Keep spendable keys out of projects you\n  test with an agent.\n- **No transactions.** No tool broadcasts, deploys, signs or takes a key.\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md).\n\n**Passing tests do not prove a contract is secure.** They show the tests you wrote pass.\nContracts that will hold value need an independent audit.\n\n## Foundry compatibility\n\nTested in CI against forge **1.8.5 and 1.8.6** on Linux, macOS and Windows. Supported range:\n`>=1.8.5 <1.9.0`. Older versions are refused. Newer ones run with a `forgeUntested` note\n(or are refused with `--strict-version`).\n\n## Development\n\n`npm test` runs the unit tests. With `FORGE_BIN=/path/to/forge` it also runs the integration\ntests against a real forge. `npm run lint` checks style. Requirement IDs in code and tests\n(FR-, NFR-, D-) refer to the project's internal specification.\n\n## License\n\nMIT © Vitaliy Chernov. See [NOTICE](NOTICE) for the licences of the dependencies.\n"}