terraform-cwd-mcp

# @yawlabs/terraform-cwd-mcp

[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=Terraform%20CWD&command=npx&args=-y%2C%40yawlabs%2Fterraform-cwd-mcp&description=Terraform%20working-dir%20truth%3A%20pinned%20provider%20schemas%2C%20plans%2C%20state%2C%20modules%2C%20upgrade%20impact&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fterraform-cwd-mcp)

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

**What is actually true in THIS Terraform working directory: the exact provider schemas pinned in your `.terraform.lock.hcl` (so coding agents stop writing arguments that do not exist, were removed, or are read-only), plus your saved plans, your state (redacted), your local and installed modules, and what a provider upgrade would break.** It complements HashiCorp's [terraform-mcp-server](https://github.com/hashicorp/terraform-mcp-server) rather than replacing it: that server answers from the Terraform Registry docs, which describe the *latest* provider release; this one answers from `terraform providers schema -json` in your root module, which describes the version you actually *locked*. Run both.

[![npm version](https://img.shields.io/npm/v/@yawlabs/terraform-cwd-mcp)](https://www.npmjs.com/package/@yawlabs/terraform-cwd-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Built and maintained by [Yaw Labs](https://yaw.sh).

## Why this one?

Your lock file says `hashicorp/aws 5.31.0`; the registry docs (and the model's training data) say whatever came later or earlier. Agents then write arguments that were added after your pin, removed before it, or are `computed`-only and cannot be set at all. `terraform validate` catches it -- after the code is written. This server lets the agent check *before* it writes.

- **Pinned, not latest** -- the source of truth is `terraform providers schema -json` run in your root module, with versions read from `.terraform.lock.hcl`.
- **Read-only, never inits** -- it never runs `terraform init` (no downloads, no backend contact, no lock-file rewrites). An uninitialized directory gets an actionable error telling you what to run.
- **Cached per lock file** -- dumps are cached in memory and on disk, keyed on the root path plus the lock file's bytes, so a provider upgrade invalidates the cache automatically. The AWS provider's schema is tens of MB; you pay for that dump once per lock-file change, not per question.
- **Small answers** -- `tf_get_schema` renders one type as a compact indented outline with `required` / `optional` / `optional+computed` / `computed (read-only)`, `[deprecated]`, `[sensitive]` and `[write_only]` flags, instead of handing the model raw JSON.
- **Cross-platform** -- macOS, Linux and Windows. Terraform is spawned directly (no shell) and its output is streamed, so there is no buffer ceiling.

## Tools

| Tool | What it does |
|---|---|
| `tf_list_providers` | Providers in the root module with their **pinned** versions and resource / data / ephemeral counts. Call this first. |
| `tf_search_types` | Find type names containing a substring (`s3_bucket`), per kind. |
| `tf_get_schema` | Every argument and nested block of one type at the pinned version, with mode and flags. Use before writing or editing a block. |
| `tf_check_arguments` | Validate dotted paths (`["bucket", "versioning.enabled"]`) and get `ok`, `ok (block)` (either with `[deprecated]`), `READ-ONLY (computed)`, `'<x>' is an attribute, not a block` or `UNKNOWN` per path. |
| `tf_summarize_plan` | Summarize a saved plan (`plan_file`: binary from `terraform plan -out`, or plan JSON) or plan JSON text (`plan_json`, e.g. an HCP run's plan fetched by the official server). Deletes and replaces first, with the attribute that forces each replace; then updates (changed paths), creates, imports, moves, forgets, drift, deferred changes and outputs; Terraform's own `Plan:` counts; a destroy warning naming renames that need a `moved` block. Prints **no values**. |
| `tf_module_interface` | Variables (exact type expression, required/optional, default, `[sensitive]` / `[not nullable]` / `[ephemeral]`, validation count), outputs and module calls of the root, a local module path, or an installed module by address (`module.network`, incl. downloaded registry/git modules). Flags module calls that are not installed or stale. No subprocess. |
| `tf_state_addresses` | Resource instance addresses in the current state (`terraform state list`), with a substring filter and `id` lookup. |
| `tf_show_resource` | One instance's attribute values from state (`terraform show -json`), with sensitive values redacted and a footer saying what was hidden and why. |
| `tf_upgrade_impact` | What breaks if a pinned provider moves to an exact version: the arguments, nested blocks, attribute reads and `provider` block arguments your configuration (root + installed modules) uses that are removed, read-only, retyped, newly required or deprecated in the target; version constraints that block it; confirmed by `terraform validate` on a temp copy. |

Every tool takes an optional `dir` (the root module); `kind` is `resource` (default), `data` or `ephemeral`.

**Division of authority with HashiCorp's official server.** This server wins on argument validity for the version you pinned and on what this directory's plan, state and modules contain. The [official server](https://github.com/hashicorp/terraform-mcp-server) wins on usage docs, latest versions, public registry modules and HCP/TFE runs. For an HCP run's plan, get its plan id there (`get_run_details`), fetch the plan with `get_plan_json_output(plan_id)` and pass the JSON to `tf_summarize_plan` as `plan_json` (those tools need the official server's `terraform` toolset and `TFE_TOKEN`).

### What is read-only, and what touches the network

- **Never written:** your root module, its `.terraform/`, its lock file and its state. `terraform init` is never run in it.
- **State tools** (`tf_state_addresses`, `tf_show_resource`) run `terraform state list` / `terraform show -json`, which never lock and never refresh. With a remote backend they read S3/GCS/HCP with the credentials the server inherited from its MCP client. Selecting a non-default workspace that does not exist would make Terraform *create* it (the s3 backend writes an empty state), so the server checks `terraform workspace list` first and refuses.
- **`tf_upgrade_impact`** downloads the target provider version with `terraform init` in a throwaway temp dir into a plugin cache (`TERRAFORM_CWD_MCP_PLUGIN_CACHE`, else your `TF_PLUGIN_CACHE_DIR`, else `<cache>/plugins`), then runs `terraform validate` on a temp copy of your configuration whose `.terraform/providers` entries are links to the packages you already have. State and `*.tfvars` are never copied. Calls are serialized (the plugin cache is not safe for concurrent installs).
- **Redaction** (`tf_show_resource`): Terraform's sensitive markers, plus any string equal to (or containing) a marked value anywhere in state, plus values under secret-like keys (`password`, `api_token`, `client_secret`, ... but not `password_length` or `secret_arn`), plus secret-shaped strings (private keys, JWTs, GitHub/GitLab/Slack/npm tokens; URL passwords are masked in place). There is deliberately no "show sensitive" switch. Unmarked derived values Terraform itself shows (e.g. `content_md5` of a sensitive file) are printed.
- Every terraform child gets `CHECKPOINT_DISABLE=1`, so no version check phones home.

Example `tf_summarize_plan` output (real plan, abridged):

```
plan (terraform 1.15.7, format 1.2): applyable, complete
totals: 1 delete, 5 replace, 1 update, 1 create, 0 read, 1 import, 1 move, 1 forget, 0 unchanged (terraform: 1 to import, 6 to add, 1 to change, 6 to destroy)
DELETE (1)
  - null_resource.gone (not in configuration)
REPLACE (5)
  -/+ local_sensitive_file.sf delete-then-create; forced by: content [sensitive]
  +/- random_string.cbd create-before-destroy; forced by: keepers
  ...
UPDATE (1)
  ~ terraform_data.cfg: input.version, output (known after apply)
WARNING: 6 object(s) will be destroyed (1 delete, 5 replace). 1 moved block(s) applied; none covers these.
```

Example `tf_upgrade_impact` output (real validate run):

```
upgrade hashicorp/random 2.3.1 -> 3.6.3 (major) for /work/infra
constraints: root pins 2.3.1 as local name rnd (change it to allow 3.6.3)
used types: resource random_password, random_id
affected arguments (2):
  random_password.p.number (main.tf:18): DEPRECATED in 3.6.3
  reads random_id.i.b64 (main.tf:36): REMOVED in 3.6.3
validate on a temp copy, 3.6.3 vs 2.3.1: 1 new error, 1 new warning, 1 warning resolved
  error main.tf:36: Unsupported attribute - This object has no argument, nested block, or exported attribute named "b64".
  warning main.tf:18 random_password.p: Attribute Deprecated - **NOTE**: This is deprecated, use `numeric` instead.
verdict: BREAKING (1 error after upgrade)
```

Example `tf_get_schema` output:

```
resource random_password (registry.terraform.io/hashicorp/random 3.9.1)
  bcrypt_hash: string computed (read-only) [sensitive] - A bcrypt hash of the generated random password. ...
  keepers: ["map","string"] optional - Arbitrary map of values that, when changed, will trigger recreation of resource. ...
  length: number required - The length of the password desired. ...
  number: bool optional+computed [deprecated] - Include numeric characters in the result. ...
  result: string computed (read-only) [sensitive] - The generated random password.
```

## Quick start

**1. Initialize the root module once** (you, not the server):

```bash
terraform init -backend=false
```

`-backend=false` is enough: the schema only needs the providers, not state.

**2. Add the server.** Claude Code, from the root module:

```bash
# macOS / Linux / WSL
claude mcp add terraform-cwd -- npx -y @yawlabs/terraform-cwd