How do I install OpenTofu Test?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does OpenTofu Test need an API key?

No required environment variable is listed on this record.

What transport does OpenTofu Test use?

OpenTofu Test runs locally over stdio.

OpenTofu Test MCP server

Q: When was OpenTofu Test last checked?

Last checked 2026-11-10. MCP server for the OpenTofu/Terraform native test framework: scaffold, mock, validate, run tests

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

docker run -i --rm ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.ogormans-deptstack-opentofu-test -- docker run -i --rm ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.ogormans-deptstack-opentofu-test": {4      "command": "docker",5      "args": [6        "run",7        "-i",8        "--rm",9        "ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0"10      ]11    }12  }13}

claude_desktop_config.json

Local · ociPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

opentofu-test-mcp

An MCP server for the OpenTofu / Terraform native test framework (.tftest.hcl / .tfmock.hcl).

LLM agents are good at writing Terraform but routinely produce broken run, assert, and mock_provider blocks because the test-framework grammar is small but unforgiving. This server gives an agent the exact block reference, scaffolds tests from a module's real variables and outputs, generates mock providers from the installed provider schema, validates test files statically, and runs the suite — so the agent can author and check tests without guessing.

It drives the tofu CLI when present and falls back to terraform.

Tools

Tool	What it does
`tf_explain_test_schema`	Reference + example for a test-framework block (`run`, `assert`, `mock_provider`, `expect_failures`, …). Empty topic returns an overview. No CLI needed.
`tf_scaffold_test`	Reads a module's variables and outputs and generates a `.tftest.hcl` starter with a run block, assertions per output, and placeholders for required variables.
`tf_gen_mock_provider`	Runs `providers schema -json` on an initialized module and emits a `mock_provider` block with `mock_resource` defaults pre-filled for computed attributes.
`tf_validate_test`	Statically checks a `.tftest.hcl` (by path or raw content): invalid `command`, asserts missing `condition`/`error_message`, duplicate run names, no run blocks. Does not run OpenTofu.
`tf_run_tests`	Runs `tofu test -json` and returns a condensed pass/fail summary with per-run status.

Install

go install github.com/ogormans-deptstack/opentofu-test-mcp@latest

Requires tofu (preferred) or terraform on PATH for the schema- and run-backed tools. tf_explain_test_schema and tf_validate_test work without either.

Prebuilt binaries for macOS, Linux, and Windows (amd64/arm64) are distributed with checksums on GitHub Releases. Native binaries still need a separately installed OpenTofu or Terraform CLI.

Container

The release workflow publishes an image with OpenTofu included:

docker run --rm -i -v "$PWD:/workspace" \
  ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0

Use -i, not -t: stdio must remain an unmodified JSON-RPC stream. Module paths passed to tools must be container paths, such as /workspace, not host paths. Only mount modules you trust: native tests can apply real infrastructure and execute provider code. The image does not inherit host cloud credentials.

Configure (client)

{
  "mcpServers": {
    "opentofu-test": {
      "command": "opentofu-test-mcp"
    }
  }
}

For Docker, configure command as docker and args as ["run", "--rm", "-i", "-v", "/absolute/module/path:/workspace", "ghcr.io/ogormans-deptstack/opentofu-test-mcp:0.1.0"].

Example

Ask the agent to "scaffold a test for this module and run it":

tf_scaffold_test { "dir": "." } → a .tftest.hcl skeleton.
tf_gen_mock_provider { "dir": "." } → mock_provider blocks (module must be initialized).
tf_validate_test { "path": "main.tftest.hcl" } → structural problems, if any.
tf_run_tests { "dir": "." } → passed=1 failed=0 errored=0 skipped=0.

Development

go test ./...
go vet ./...

Automated MCP checks with Inspector

Requires Node.js 22.19+, Go, and OpenTofu 1.13.1 on PATH. Inspector is pinned in package-lock.json; Node is development tooling, not a server runtime dependency.

npm ci
go build -o dist/opentofu-test-mcp .
npm run test:mcp

This launches the built server through the Inspector CLI over real stdio. It checks initialization, the exact five-tool inventory, portable input schemas (tools/list --strict), structured output, all five tools, a missing-input error, and both passing and deliberately failing native tests. Fixtures use OpenTofu's built-in terraform_data provider, so no cloud credentials or provider downloads are needed. The failing fixture is intentional. Tests work in a temporary copy and use an in-memory Inspector secret store.

To check the container with the same suite:

docker build -t opentofu-test-mcp:local .
MCP_IMAGE=opentofu-test-mcp:local npm run test:mcp

To check another build, set MCP_SERVER=/absolute/path/to/opentofu-test-mcp. CI runs both native and container smoke tests in addition to Go race tests.

For individual checks or interactive debugging:

# Machine-readable tool inventory; non-zero on schema portability errors.
npx --no-install @modelcontextprotocol/inspector --cli ./dist/opentofu-test-mcp \
  --method tools/list --strict --format json --stored-auth-only

# A single tool call, without starting a browser.
npx --no-install @modelcontextprotocol/inspector --cli ./dist/opentofu-test-mcp \
  --method tools/call --tool-name tf_explain_test_schema \
  --tool-args-json '{"topic":"run"}' --format json --stored-auth-only

# Web Inspector for inspecting requests, responses, and schemas.
npm run inspect

Before contributing an MCP change, reproduce the behavior using a disposable fixture, add assertions for the regression and its error path, then run the Go and Inspector suites. Assert the JSON result, not just process exit status: Inspector exits 5 for isError: true and 6 for strict schema failures, but a valid tf_validate_test response with valid: false or a native test summary with failed > 0 still exits successfully. Inspector checks complement, not replace, unit tests; they do not prove semantic correctness of every Terraform expression or compatibility with every MCP client.

The Inspector documentation also describes the TUI and experimental mcpdo persistent connection client. The CLI is sufficient for this server's stateless requests; use a persistent client for future session-dependent flows. The pinned CLI defaults to the legacy protocol era, matching the server SDK; do not force modern-era negotiation without upgrading and testing the server first. Keep the web UI's default loopback binding and authentication enabled, and do not put secrets in fixture files or captured transcripts.

Releasing

Update server.json's top-level version and OCI identifier tag together. Commit the changes and wait for CI on that commit.
Tag that tested commit (for example git tag v0.1.0) and push the tag. .github/workflows/release.yml refuses mismatched versions and reruns CI.
The workflow builds six native archives with checksums, creates a GitHub release, and publishes a Linux amd64/arm64 OCI image. The image embeds the release version and the MCP Registry ownership label io.modelcontextprotocol.server.name.
On the first release, GitHub may create the GHCR package as private. Change its package settings to public, then rerun failed workflow jobs. The workflow checks anonymous image access before registry publication.
The final job validates server.json and publishes it using GitHub Actions OIDC (id-token: write), without a long-lived registry secret.

Registry publishing follows the official OCI package requirements and GitHub Actions guide. The registry hosts metadata, not the binary or image, so the package must be publicly available first. Do not submit a PR to the registry repository.

OCI package entries must not contain registryBaseUrl, version, or fileSha256; the full registry and version belong in identifier. The publisher's validate command does not perform every package-specific check that publish does, so the smoke suite checks those constraints too.

To retry registry publication after a metadata-only correction without moving the release tag or rebuilding artifacts, push the correction and dispatch the registry-only workflow: gh workflow run publish-mcp.yml --ref main. It checks the existing public image and uses OIDC, just like the tag-triggered release.

For registry publication outside Actions:

mcp-publisher validate server.json
mcp-publisher login github
mcp-publisher publish server.json
curl --fail --get 'https://registry.modelcontextprotocol.io/v0.1/servers' \
  --data-urlencode 'search=io.github.ogormans-deptstack/opentofu-test'

Authenticate as ogormans-deptstack (or an authorized namespace owner), not an unrelated GitHub account. To build native archives locally without publishing: bash scripts/build-release.sh 0.1.0.

License

MIT — see LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install OpenTofu Test?

Does OpenTofu Test need an API key?

What transport does OpenTofu Test use?

When was OpenTofu Test last checked?

Documentation

opentofu-test-mcp

Tools

Install

Container

Configure (client)

Example

Development

Automated MCP checks with Inspector

Releasing

License