Manage Terraform Cloud via Conversational AI

Terraform Cloud MCP Server

A Model Context Protocol (MCP) server that integrates AI assistants with the Terraform Cloud API, allowing you to manage your infrastructure through natural conversation. Built with Pydantic models and structured around domain-specific modules, this server is compatible with any MCP-supporting platform including Claude, Claude Code CLI, Claude Desktop, Cursor, Copilot Studio, and others.

Features

• Account Management: Get account details for authenticated users or service accounts.
• Workspace Management: Create, read, update, lock/unlock workspaces, and optionally delete workspaces (with safety controls).
• Project Management: Create, list, update projects, and optionally delete projects; manage project tag bindings and move workspaces between projects.
• Run Management: Create runs, list runs, get run details, apply/discard/cancel runs.
• Plan Management: Retrieve plan details and JSON execution output with advanced HTTP redirect handling.
• Apply Management: Get apply details and recover from failed state uploads.
• Organization Management: List, create, update organizations, view organization entitlements, and optionally delete organizations (with safety controls).
• Cost Estimation: Retrieve detailed cost estimates for infrastructure changes including proposed monthly costs, prior costs, resource counts, and usage projections.
• Assessment Results: Retrieve health assessment details, JSON output, schema files, and logs from Terraform Cloud health assessments.
• State Version Management: List, retrieve, create, and download state versions; get current state for workspaces.
• State Version Outputs: List and retrieve specific outputs from state versions including values and sensitivity information.
• Variables Management: Complete workspace variable and variable set management including creation, updates, assignments, and optionally deletion (with safety controls).

Performance Features

• Audit-Safe Response Filtering: Conservative token optimization (5-15% reduction) with 100% audit compliance - preserves all user accountability, security configuration, and change tracking data for comprehensive compliance scenarios.

Safety Features

• Destructive Operation Controls: Delete operations are disabled by default and require explicit enablement via environment variable
• Read-Only Mode: All write operations can be disabled with READ_ONLY_TOOLS=true for maximum safety in production environments
• Destructive Hints: MCP clients receive proper destructive operation warnings for potentially dangerous tools
• Environment-Based Safety: Production and development environments can have different safety configurations

Quick Start

Prerequisites

• Python 3.12+
• MCP (includes FastMCP and development tools)
• uv package manager (recommended) or pip
• Terraform Cloud API token

Creating a Terraform Cloud API Token

To use this MCP server, you need a Terraform Cloud (or Terraform Enterprise) API token:

1. Sign in to HCP Terraform (or your Terraform Enterprise instance)
2. Click your avatar in the top-right corner and select User Settings
3. Navigate to Tokens in the left sidebar
4. Click Create an API token
5. Provide a description (e.g., "MCP Server")
6. Set an expiration date (recommended for security)
7. Click Generate token
8. Copy the token immediately - it will only be shown once

Use this token as your TFC_TOKEN environment variable in the configuration steps below.

For more information about API token types and permissions, see the HCP Terraform API Tokens documentation.

Environment Variables

• TFC_TOKEN - Terraform Cloud API token (required)
• TFC_ADDRESS - Terraform Cloud/Enterprise address (optional, defaults to https://app.terraform.io)
• ENABLE_DELETE_TOOLS - Enable/disable destructive operations (optional, defaults to false)
• READ_ONLY_TOOLS - Enable only read-only operations (optional, defaults to false)
• ENABLE_RAW_RESPONSE - Return raw vs filtered responses (optional, defaults to false)

Installation

Option 1: Local Installation

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install package
uv pip install .

Option 2: Docker Installation

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Build the Docker image
docker build -t terraform-cloud-mcp:latest .

Adding to Claude Environments

Adding to Claude Code CLI

# Add to Claude Code with your Terraform Cloud token
claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=false -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To use a self-hosted Terraform Enterprise instance:
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e TFC_ADDRESS=https://terraform.example.com -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To enable delete operations (use with caution):
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=true -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

Adding to Claude Desktop

Create a claude_desktop_config.json configuration file:

• mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• win: %APPDATA%\Claude\claude_desktop_config.json

Local Installation Configuration:

{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "/path/to/uv", # Get this by running: `which uv`
      "args": [
        "--directory",
        "/path/to/your/terraform-cloud-mcp", # Full path to this project
        "run",
        "terraform-cloud-mcp"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here", # replace with actual token
        "TFC_ADDRESS": "https://app.terraform.io", # optional, change for self-hosted TFE
        "ENABLE_DELETE_TOOLS": "false", # set to "true" to enable destructive operations/tools
        "READ_ONLY_TOOLS": "false" # set to  "true" to only enable ready-only operations/tools
      }
    }
  }
}

Docker Configuration:

{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TFC_TOKEN",
        "-e", "TFC_ADDRESS",
        "-e", "ENABLE_DELETE_TOOLS",
        "-e", "READ_ONLY_TOOLS",
        "terraform-cloud-mcp:latest"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here",
        "TFC_ADDRESS": "https://app.terraform.io",
        "ENABLE_DELETE_TOOLS": "false",
        "READ_ONLY_TOOLS": "false"
      }
    }
  }
}

Replace your_terraform_cloud_token with your actual Terraform Cloud API token.

Other MCP-Compatible Platforms

For other platforms (like Cursor, Copilot Studio, or Glama), follow their platform-specific instructions for adding an MCP server. Most platforms require:

1. The server path or command to start the server.
2. Environment variables for the Terraform Cloud API token (TFC_TOKEN).
3. Optional environment variable for self-hosted Terraform Enterprise (TFC_ADDRESS).
4. Optional environment variable to enable delete operations (ENABLE_DELETE_TOOLS=true for destructive operations).
5. Optional environment variable for read-only mode (READ_ONLY_TOOLS=true to disable all write operations).
6. Configuration to auto-start the server when needed.

Available Tools

Note: When READ_ONLY_TOOLS=true, all create, update, delete, apply, and state modification operations are disabled. Only read operations (list, get, view) remain available.

Account Tools

• get_account_details(): Gets account information for the authenticated user or service account.

Workspace Management Tools

List & Search

• list_workspaces(organization, page_number, page_size, search): List and filter workspaces.
• get_workspace_details(workspace_id, organization, workspace_name): Get detailed information about a specific workspace.

Create & Update

• create_workspace(organization, name, params): Create a new workspace with optional parameters.
• update_workspace(organization, workspace_name, params): Update an existing workspace's configuration.

Delete (Requires ENABLE_DELETE_TOOLS=true)

• delete_workspace(organization, workspace_name): Delete a workspace and all its content.
• safe_delete_workspace(organization, workspace_name): Delete only if the workspace isn't managing any resources.

Note: Delete operations are disabled by default for safety. Set ENABLE_DELETE_TOOLS=true to enable these destructive operations.

Lock & Unlock

• lock_workspace(workspace_id, reason): Lock a workspace to prevent runs.
• unlock_workspace(workspace_id): Unlock a workspace to allow runs.
• force_unlock_workspace(workspace_id): Force unlock a workspace locked by another user.

Run Management Tools

• create_run(workspace_id, params): Create and queue a Terraform run in a workspace using its ID.
• list_runs_in_workspace(workspace_id, ...): List and filter runs in a specific workspace using its ID.
• list_runs_in_organization(organization, ...): List and filter runs across an entire organization.
• get_run_details(run_id): Get detailed information about a specific run.
• apply_run(run_id, comment): Apply a run waiting for confirmation.
• discard_run(run_id, comment): Discard a run waiting for confirmation.
• cancel_run(run_id, comment): Cancel a run currently planning or applying.
• force_cancel_run(run_id, comment): Forcefully cancel a run immediately.
• force_execute_run(run_id): Forcefully execute a pending run by canceling prior runs.

Plan Management Tools

• get_plan_details(plan_id): Get detailed information about a specific plan.
• get_plan_json_output(plan_id): Retrieve the JSON execution plan for a specific plan with proper redirect handling.
• get_run_plan_json_output(run_id): Retrieve the JSON execution plan from a run with proper redirect handling.
• get_plan_logs(plan_id): Retrieve logs from a plan operation.

Apply Management Tools

• get_apply_details(apply_id): Get detailed information about a specific apply.
• get_errored_state(apply_id): Retrieve the errored state from a failed apply for recovery.
• get_apply_logs(apply_id): Retrieve logs from an apply operation.

Project Management Tools

• create_project(organization, name, params): Create a new project with optional parameters.
• update_project(project_id, params): Update an existing project's configuration.
• list_projects(organization, ...): List and filter projects in an organization.
• get_project_details(project_id): Get detailed information about a specific project.
• delete_project(project_id): Delete a project (fails if it contains workspaces). Requires ENABLE_DELETE_TOOLS=true
• list_project_tag_bindings(project_id): List tags bound to a project.
• add_update_project_tag_bindings(project_id, tag_bindings): Add or update tag bindings on a project.
• move_workspaces_to_project(project_id, workspace_ids): Move workspaces into a project.

Organization Management Tools

• get_organization_details(organization): Get detailed information about a specific organization.
• get_organization_entitlements(organization): Show entitlement set for organization features.
• list_organizations(page_number, page_size, query, query_email, query_name): List and filter organizations.
• create_organization(name, email, params): Create a new organization with optional parameters.
• update_organization(organization, params): Update an existing organization's settings.
• delete_organization(organization): Delete an organization and all its content. Requires ENABLE_DELETE_TOOLS=true

Cost Estimation Tools

• get_cost_estimate_details(cost_estimate_id): Get detailed information about a specific cost estimate, including resource counts (matched and unmatched), prior monthly cost, proposed monthly cost, and delta monthly cost estimations. Use run relationships to find cost estimate IDs for specific runs.

Assessment Results Tools

• get_assessment_result_details(assessment_result_id): Get detailed information about a specific health assessment result.
• get_assessment_json_output(assessment_result_id): Retrieve the JSON execution plan from an assessment result.
• get_assessment_json_schema(assessment_result_id): Retrieve the JSON schema file from an assessment result.
• get_assessment_log_output(assessment_result_id): Retrieve logs from an assessment result operation.

State Version Management Tools

• list_state_versions(organization, workspace_name, page_number, page_size, filter_status): List and filter state versions in a workspace.
• get_current_state_version(workspace_id): Get the current state version for a workspace.
• get_state_version(state_version_id): Get details for a specific state version.
• create_state_version(workspace_id, serial, md5, params): Create a new state version in a workspace.
• download_state_file(state_version_id, json_format): Download the raw or JSON formatted state file.

State Version Outputs Tools

• list_state_version_outputs(state_version_id, page_number, page_size): List outputs for a specific state version.
• get_state_version_output(state_version_output_id): Get details for a specific state version output.

Variables Management Tools

Workspace Variables

• list_workspace_variables(workspace_id): List all variables (Terraform and environment) for a workspace.
• create_workspace_variable(workspace_id, key, category, params): Create a new variable in a workspace.
• update_workspace_variable(workspace_id, variable_id, params): Update an existing workspace variable.
• delete_workspace_variable(workspace_id, variable_id): Delete a workspace variable. Requires ENABLE_DELETE_TOOLS=true

Variable Sets

• list_variable_sets(organization, page_number, page_size): List variable sets in an organization.
• get_variable_set(varset_id): Get details for a specific variable set.
• create_variable_set(organization, name, params): Create a new variable set.
• update_variable_set(varset_id, params): Update an existing variable set.
• delete_variable_set(varset_id): Delete a variable set and all its variables. Requires ENABLE_DELETE_TOOLS=true
• assign_variable_set_to_workspaces(varset_id, workspace_ids): Assign a variable set to workspaces.
• unassign_variable_set_from_workspaces(varset_id, workspace_ids): Remove a variable set from workspaces.
• assign_variable_set_to_projects(varset_id, project_ids): Assign a variable set to projects.
• unassign_variable_set_from_projects(varset_id, project_ids): Remove a variable set from projects.

Variable Set Variables

• list_variables_in_variable_set(varset_id): List all variables in a variable set.
• create_variable_in_variable_set(varset_id, key, category, params): Create a variable in a variable set.
• update_variable_in_variable_set(varset_id, var_id, params): Update a variable in a variable set.
• delete_variable_from_variable_set(varset_id, var_id): Delete a variable from a variable set. Requires ENABLE_DELETE_TOOLS=true

Note: Variable management includes both Terraform input variables and environment variables. Sensitive variables have their values hidden for security. Delete operations are disabled by default and require ENABLE_DELETE_TOOLS=true.

Development Guide

For detailed development guidance including code standards, Pydantic patterns, and contribution workflows, see our Development Documentation.

Quick Development Setup

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with development dependencies
uv pip install -e .
uv pip install black mypy pydantic ruff

Basic Development Commands

# Run the server in development mode
mcp dev terraform_cloud_mcp/server.py

# Run tests and quality checks
uv run -m mypy .
uv run -m ruff check .
uv run -m black .

For detailed information on code organization, architecture, development workflows, and code quality guidelines, refer to docs/DEVELOPMENT.md.

Documentation

The codebase includes comprehensive documentation:

• Code Comments: Focused on explaining the "why" behind implementation decisions
• Docstrings: All public functions and classes include detailed docstrings
• Implementation References: Development documentation now references actual code examples rather than using code snippets
• Example Files: The docs/ directory contains detailed examples for each domain:
  • docs/FILTERING_SYSTEM.md: Comprehensive guide to the audit-safe response filtering system (5-15% token reduction, 100% audit compliance)
  • docs/DEVELOPMENT.md: Development standards and coding guidelines with references to actual code
  • docs/API_REFERENCES.md: Terraform Cloud API documentation links with implementation status
  • docs/CONTRIBUTING.md: Guidelines for contributing to the project
  • docs/models/: Reference documentation for all model types
  • docs/tools/: Detailed reference documentation for each tool
  • docs/conversations/: Sample conversation flows with the API

Troubleshooting

1. Check server logs (debug logging is enabled by default)
2. Use the MCP Inspector (http://localhost:5173) for debugging
3. Debug logging is already enabled in server.py:

   import logging
   logging.basicConfig(level=logging.DEBUG)