Terraform Cloud MCP Server

Features

• **Account Management**: Get account details for authenticated users or service accounts.

• **Workspace Management**: Create, read, update, delete, lock/unlock workspaces.

• **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, delete organizations, and view organization entitlements.

• **Future Features**: Variables management, state versions, and more.

Quick Start

Prerequisites

• Python 3.12+

• MCP (includes FastMCP and development tools)

• `uv` package manager (recommended) or `pip`

• Terraform Cloud API token

Installation

Adding to Claude Environments

Adding to Claude Code CLI

Adding to Claude Desktop

• mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• win: %APPDATA%\Claude\claude_desktop_config.json

Other MCP-Compatible Platforms

1. The server path or command to start the server.

2. Environment variables for the Terraform Cloud API token.

3. Configuration to auto-start the server when needed.

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

• `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 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.

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.

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.

Development Guide

Quick Development Setup

Basic Development Commands

Documentation

• **Code Comments**: Focused on explaining the "why" behind implementation decisions

• **Docstrings**: All public functions and classes include detailed docstrings

• **Example Files**: The `docs/` directory contains detailed examples for each domain: - `docs/DEVELOPMENT.md`: Development standards and coding guidelines - `docs/CONTRIBUTING.md`: Guidelines for contributing to the project - `docs/models/`: Usage examples for all model types - `docs/tools/`: Detailed usage examples 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`: ```python import logging logging.basicConfig(level=logging.DEBUG) ```

Contributing