{
  "markdown": "# mcp-server-terraform\n\n[![CI](https://github.com/RajeevSirohi/mcp-server-terraform/actions/workflows/ci.yml/badge.svg)](https://github.com/RajeevSirohi/mcp-server-terraform/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/%40rajsir%2Fmcp-server-terraform)](https://www.npmjs.com/package/@rajsir/mcp-server-terraform)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets Claude manage Terraform infrastructure through natural language.\n\n> Run plans, apply changes, inspect state, and diagnose failures — all from a Claude conversation.\n\n## What it does\n\nInstead of switching to a terminal to run `terraform plan`, you can ask Claude:\n\n> \"Plan the changes in `/infra/staging` and explain what will change\"\n\n> \"Apply it — but only if no resources will be destroyed\"\n\n> \"Show me all the outputs from the prod workspace\"\n\n> \"Something broke after the last apply — diagnose it\"\n\nThe server translates these into real `terraform` CLI commands on your machine, with a built-in safety confirmation flow before any destructive operation runs.\n\n## Tools\n\n| Tool | Description | Destructive |\n|------|-------------|-------------|\n| `tf_init` | Initialize a Terraform working directory | No |\n| `tf_validate` | Validate configuration syntax | No |\n| `tf_plan` | Run a plan and return the diff + risk/cost summary | No |\n| `tf_apply` | Apply changes (requires `confirmed: true`) | Yes |\n| `tf_destroy` | Destroy infrastructure (requires `confirmed: true`) | Yes |\n| `tf_output` | Read output values from state | No |\n| `tf_state` | List, show, move, or remove state entries | Partial |\n| `tf_workspace` | List, show, select, or create workspaces | No |\n| `tf_preflight` | Check provider CLI authentication before running | No |\n| `tf_drift` | Detect resources changed outside Terraform | No |\n| `tf_resource` | Import, taint, untaint, or refresh resources | Yes |\n\n### Plan risk & cost summary\n\nEvery plan (and every apply preview) is analyzed via `terraform show -json` and\nannotated with a structured summary — destroyed resources are called out, and\nalways-on resources that commonly cause bill shock are flagged with rough\nmonthly costs:\n\n```\n── Plan Summary ──\n+ 3 create, ~ 1 update, - 0 destroy, ± 0 replace\n\n💸 EXPENSIVE — always-on resources being created:\n   ⚠ aws_nat_gateway.main (~$32/month + data processing if left running)\n   Remember to tf_destroy when you're done experimenting.\n```\n\nCost-flagged resource types include NAT gateways, load balancers, EKS/AKS/GKE\ncontrol planes, RDS/Cloud SQL instances, ElastiCache, Redshift, MSK, and\nAzure Firewall (~$900/month!).\n\n### Drift detection\n\n`tf_drift` runs a refresh-only plan and reports resources that were changed\noutside Terraform (e.g. manually in the cloud console), with the changed\nattribute names and remediation options.\n\n### Audit logging\n\nSet `AUDIT_LOG_PATH` to a file path and every tool call is appended as a JSON\nline with timestamp, tool name, outcome, and duration. Variable **values** are\nalways redacted (`db_password=<redacted>`) — only names are logged.\n\n### Confirmation flow\n\n`tf_apply` and `tf_destroy` use a two-step safety flow:\n\n1. **First call** (no `confirmed`) → runs `terraform plan`, shows the diff, does nothing else\n2. **Second call** (`confirmed: true`) → actually applies or destroys\n\nClaude is instructed to never pass `confirmed: true` without first presenting the plan to you.\n\n### Prompt\n\nThe server exposes a `/tf-diagnose` prompt that guides Claude through a systematic 5-step diagnosis of plan or apply failures.\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org) 18 or later\n- [Terraform](https://developer.hashicorp.com/terraform/downloads) CLI on your PATH\n- [Claude Desktop](https://claude.ai/download) (or any MCP-compatible client)\n\n## Installation\n\nNo install needed — run it straight from npm:\n\n```bash\nnpx @rajsir/mcp-server-terraform\n```\n\nOr, for development, from source:\n\n```bash\ngit clone https://github.com/RajeevSirohi/mcp-server-terraform.git\ncd mcp-server-terraform\nnpm install\nnpm run build\n```\n\n## Claude Desktop setup\n\nAdd to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"terraform\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@rajsir/mcp-server-terraform\"]\n    }\n  }\n}\n```\n\n(If running from source instead, use `\"command\": \"node\"` with `\"args\": [\"/absolute/path/to/dist/index.js\"]`.)\n\nRestart Claude Desktop. You should see a hammer icon indicating tools are available.\n\n## Usage\n\nOnce connected, just talk to Claude about your Terraform workspaces in plain language. Some examples:\n\n### First time in a new workspace\n\n> \"Initialize the terraform config in `C:\\infra\\staging` and check if I'm logged into the right cloud accounts\"\n\nClaude runs `tf_init`, then `tf_preflight` — if you're not authenticated it tells you exactly which command to run (`az login`, `aws configure`, ...).\n\n### The everyday plan → review → apply loop\n\n> \"Plan the changes in `C:\\infra\\staging` and explain what will change\"\n\nYou get the plan diff plus a summary: how many resources created/updated/destroyed, anything destructive called out explicitly, and cost warnings for expensive always-on resources.\n\n> \"Looks good, apply it\"\n\nClaude shows the plan preview one more time and asks for your confirmation — nothing is applied until you say yes. This two-step gate is built into the server itself, not just the prompt, so Claude *cannot* skip it.\n\n### Checking on your infrastructure\n\n> \"Did anyone change anything outside terraform in the prod workspace?\"\n\n`tf_drift` compares state against reality and reports what was modified in the console, with options to accept or revert.\n\n> \"Show me all the outputs\" · \"List everything in state\" · \"What workspaces exist?\"\n\n### Learning / experimenting (e.g. cert prep)\n\n> \"Apply the VPC lab in `C:\\labs\\vpc`, and when I say 'done' destroy everything\"\n\nThe cost flags are your friend here — if a lab creates a NAT gateway or EKS cluster, the plan summary warns you what it costs per month if forgotten:\n\n```\n💸 EXPENSIVE — always-on resources being created:\n   ⚠ aws_nat_gateway.main (~$32/month + data processing if left running)\n   Remember to tf_destroy when you're done experimenting.\n```\n\n### Fixing things\n\n> \"terraform plan is failing in `C:\\infra\\staging` — diagnose it\"\n\nThe `/tf-diagnose` prompt walks Claude through validate → providers → plan → state → outputs systematically. There's also `/tf-login` for step-by-step authentication setup per provider.\n\n> \"Import the S3 bucket `my-legacy-bucket` into state as `aws_s3_bucket.legacy`\"\n\n> \"Taint the web server so it gets recreated on the next apply\"\n\n### Recommended setup for shared or cautious environments\n\nRun with `ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true` (see Safety modes below) so apply/destroy are unavailable entirely, and set `AUDIT_LOG_PATH` so every operation is logged.\n\n## Safety modes\n\nControl which tools are available via environment variables:\n\n| Variable | Effect |\n|----------|--------|\n| `ALLOW_ONLY_READONLY_TOOLS=true` | Only `tf_validate`, `tf_plan`, `tf_output` |\n| `ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true` | Blocks `tf_apply`, `tf_destroy`, `tf_state mv/rm` |\n| `ALLOWED_TOOLS=tf_plan,tf_output` | Explicit comma-separated allowlist |\n\nExample — read-only mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"terraform\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/dist/index.js\"],\n      \"env\": {\n        \"ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\n```bash\nnpm run dev       # watch mode (recompiles on save)\nnpm test          # run tests\nnpm run build     # production build\n```\n\n### Project structure\n\n```\nsrc/\n  index.ts                  # MCP server entry point, tool registration\n  config/                   # (reserved for future config/telemetry)\n  models/\n    common-parameters.ts    # Shared Zod schemas\n  security/\n    tf-flags.ts             # Dangerous flag blocking\n  tools/\n    tf-init.ts\n    tf-validate.ts\n    tf-plan.ts\n    tf-apply.ts             # Two-step confirmation flow\n    tf-destroy.ts           # Two-step confirmation flow\n    tf-output.ts\n    tf-state.ts\n    tf-workspace.ts\n  utils/\n    terraform-runner.ts     # Core exec wrapper, workspace switching\n  prompts/\n    index.ts                # /tf-diagnose prompt\ntests/\n  tf-flags.test.ts\n  tf-apply.test.ts\n```\n\n### Adding a new tool\n\n1. Create `src/tools/tf-yourcommand.ts` — export a `*Schema` const and an async handler function\n2. Import both in `src/index.ts`\n3. Add the schema to `readonlyTools` or `destructiveTools` array\n4. Add a `case` in the `CallToolRequestSchema` handler switch\n\n## Roadmap\n\n- [ ] Terraform Cloud / Enterprise API support (Phase 2)\n- [ ] OpenTelemetry tracing\n- [ ] SSE / streamable HTTP transport for remote deployments\n- [ ] Docker image on GitHub Container Registry\n- [x] Plan risk & cost analysis\n- [x] Drift detection\n- [x] Import / taint / untaint / refresh\n- [x] Audit logging\n- [x] CI (build, test matrix, e2e against real terraform)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 9300,
  "sha": "3e8f88bd0ea529556ebe4630e3c34d5eb4dd29156b759bbb9c2104e320392d00",
  "repo_slug": "rajeevsirohi/mcp-server-terraform",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rajeevsirohi_mcp_server_terraf_16d23f47/readme"
}