Terraform Cloud MCP server for AI agents

The Terraform Cloud MCP server is a powerful interface that integrates AI assistants with the Terraform Cloud API, enabling infrastructure management through natural language conversations. Compatible with various MCP-supporting platforms like Claude, Cursor, and Copilot Studio, it offers robust functionality for managing your Terraform Cloud resources.

Installation

Prerequisites

Python 3.12+
Terraform Cloud API token
uv package manager (recommended) or pip

Creating a Terraform Cloud API Token

Sign in to HCP Terraform
Click your avatar in the top-right corner and select User Settings
Navigate to Tokens in the left sidebar
Click Create an API token
Provide a description (e.g., "MCP Server")
Set an expiration date
Click Generate token
Copy the token immediately - it will only be shown once

Environment Variables

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

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 .

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 .

Configuring with AI Assistants

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",
      "args": [
        "--directory",
        "/path/to/your/terraform-cloud-mcp",
        "run",
        "terraform-cloud-mcp"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here",
        "TFC_ADDRESS": "https://app.terraform.io",
        "ENABLE_DELETE_TOOLS": "false",
        "READ_ONLY_TOOLS": "false"
      }
    }
  }
}

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"
      }
    }
  }
}

Available Tools

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.

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 & Apply 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.
get_run_plan_json_output(run_id): Retrieve the JSON execution plan from a run.
get_plan_logs(plan_id): Retrieve logs from a plan operation.
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).
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.

Cost Estimation & Assessment Tools

get_cost_estimate_details(cost_estimate_id): Get detailed information about a specific cost estimate.
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

list_workspace_variables(workspace_id): List all variables 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.
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.

Troubleshooting

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "terraform-cloud-mcp" '{"command":"terraform-cloud-mcp","env":{"TFC_TOKEN":"${TFC_TOKEN}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "terraform-cloud-mcp": {
            "command": "terraform-cloud-mcp",
            "env": {
                "TFC_TOKEN": "${TFC_TOKEN}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "terraform-cloud-mcp": {
            "command": "terraform-cloud-mcp",
            "env": {
                "TFC_TOKEN": "${TFC_TOKEN}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect