Forge Test MCP
MCP server that runs Foundry tests and builds and returns compact failure reports
- Pricing
- Open source
- Platforms
- CLI, self-hosted, API
- Runs
- Locally
- Version
- 0.1.0
- Listing updated
- today
Similar MCP servers
About Forge Test MCP
Forge Test MCP is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.
The README says the server wraps forge test and forge build and returns each failing test with its kind, decoded reason, fuzz counterexample or invariant call sequence, console logs and a shortened decoded trace. Results are meant to be read by an AI coding agent rather than a person scanning raw forge output.
When forge does not actually run the tests, such as on a compile error, no matching tests, a timeout or a missing forge binary, the tool returns an error with a code and hint instead of reporting zero failures. It is started over stdio with npx from a Foundry project directory and is documented for clients including Claude Code, Codex and Cursor, although the author notes these have not yet all been checked in practice.
The README is explicit that running tests executes project Solidity with the user's rights, that FFI stays off unless enabled, and that no tool sends transactions or handles keys. It is aimed at Solidity developers who already use Foundry and want agents to iterate on test failures.
Install
Run in a terminal
claude mcp add forge-test-mcp -- npx -y forge-test-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"forge-test-mcp": {
"command": "npx",
"args": [
"-y",
"forge-test-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"forge-test-mcp": {
"command": "npx",
"args": [
"-y",
"forge-test-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"forge-test-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"forge-test-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"forge-test-mcp": {
"command": "npx",
"args": [
"-y",
"forge-test-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"forge-test-mcp": {
"command": "npx",
"args": [
"-y",
"forge-test-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Tools this server provides (3)
Taken from the project documentation; the running server may differ.
- run_tests
- Runs forge test with filters, fuzz run count, traces and a size limit.
- explain_failure
- Re-runs one named test at high verbosity and returns its reason, counterexample, logs and trace.
- build
- Runs forge build and returns compiler errors and warnings, optionally forcing a full recompile.
What it does
- Structured failure reports
- Each failing test comes back with its kind, decoded reason, and shortened trace in a fixed JSON shape.
- Fuzz and invariant counterexamples
- Fuzz counterexamples and invariant call sequences are included so the failing input can be inspected.
- Explicit error reporting
- When forge does not run the tests, an error code and hint are returned rather than a passing-looking result.
- Filtered test runs
- Runs can be narrowed by test name, contract or path, with a fuzz run count and a size cap on output.
- Build diagnostics
- The build tool returns compiler errors and warnings with file, line, column and code.
- Secret redaction
- Values of variables named like private keys, secrets and RPC URLs are replaced in output.
Good for
- Letting a coding agent read Foundry test failures and fix the contract code
- Getting compact invariant failure sequences for debugging stateful fuzz tests
- Surfacing Solidity compile errors to an agent with file and line locations
- Running a single failing test at high verbosity to inspect its trace
Pricing
Open source
MIT licensed, self-run from npm or Docker
Forge Test MCP FAQ
Which forge versions are supported?
The README lists the supported range as forge 1.8.5 or later within 1.8.x. Newer versions run but are flagged as untested unless --strict-version is used.
Does it send transactions or handle private keys?
The README states that no tool sends transactions, deploys, signs or accepts keys.
Is FFI enabled by default?
No. FFI stays off unless the server is started with --allow-ffi, even when foundry.toml enables it.
How is it installed?
The README gives an npx entry using forge-test-mcp@0.1.0 and a Docker option that bundles forge 1.8.6.
Is Forge Test MCP free?
Yes. Forge Test MCP is open source, so you can use and self-host it for free.
How do I add Forge Test MCP to Claude Code?
Run this command in your terminal: claude mcp add forge-test-mcp -- npx -y forge-test-mcp
What are the best alternatives to Forge Test MCP?
The closest alternatives to Forge Test MCP are MCP Failure Lab, ForgeOps, Forge by UI8, Laravel Forge MCP by usefulapi and MCP Foundry — Build, Test & Publish MCP Servers.
Where this comes from
- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.
