Forge Test Mcp

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 test executes 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 when foundry.toml enables 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.

Requirements

• Node.js 22 or later.
• Foundry with 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.
• The project's compiler version installed once: run forge build in 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", "[email protected]"]    }  }}

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:

  toml

  [mcp_servers.forge-test]command = "npx"args = ["-y", "[email protected]"]

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 build

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

Options go after the package name in args. Only the user sets them; no tool argument can.

Tools

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:

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, .env contents, 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_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.
• 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 through vm.createSelectFork and RPC endpoints.
• No shell. forge is started with an argument list. Tool arguments are validated and passed as single --flag=value arguments.
• Secrets. forge loads the project's .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.
• 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.