Terraform Cloud MCP Server for AI-Powered Infrastructure

Overview

Terraform Cloud MCP Server enables conversational, AI-assisted management of Terraform Cloud infrastructure. It implements the Model Context Protocol (MCP) to expose Terraform Cloud operations as “tools” an AI assistant can call, bridging natural-language prompts and the Terraform Cloud API. Developers can integrate this server with a chat-based assistant to create workspaces, run plans, inspect runs, and manage variables via simple conversation.

This server is useful when you want to pair human intent with programmatic safety and auditability. By converting assistant actions into explicit API operations, teams keep Terraform Cloud workflow and governance intact while accelerating common tasks (e.g., creating workspaces, running plans, reviewing diffs) through natural language or automated agent flows.

Features

• Exposes Terraform Cloud capabilities as MCP tools for AI assistants
• Create, list, and manage workspaces and runs (plan/apply)
• Inspect plans, run statuses, and logs for decision-making
• Read and update workspace variables and VCS settings
• Audit-friendly operations: every action maps to a Terraform Cloud API call
• Configurable authentication and environment via ENV or .env files
• Docker-friendly for easy deployment in development and CI environments

Installation / Configuration

Prerequisites:

• Docker (recommended) or Python 3.9+ and pip
• A Terraform Cloud API token (user or organization token)
• Optional: an API key for your chosen LLM provider if you plan to attach an AI assistant

Quick start (Docker):

git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

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

# Create a .env file (see example below), then run
docker run --env-file .env -p 8080:8080 terraform-cloud-mcp

Quick start (local/Python):

git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Optional: create a virtualenv
python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

# Run the server (example)
python -m server.main --port 8080

Example .env

# Terraform Cloud
TFC_TOKEN=ptkn_XXXXXXXXXXXXXXXXXXXX
TFC_ORGANIZATION=my-org

# Server runtime
MCP_HOST=0.0.0.0
MCP_PORT=8080

# Optional AI provider key (if connecting an LLM assistant)
OPENAI_API_KEY=sk-XXXXXXXXXXXX

Common environment variables

Adjust network, logging, and authentication in the repository’s config files (config.yaml or similar) before deploying to production.

Available Resources

The server exposes a set of MCP-compatible tools that represent Terraform Cloud capabilities. Typical resources/tools include:

• terraform_cloud.workspaces — list, create, update workspaces; manage VCS and execution mode
• terraform_cloud.runs — start plan/apply runs, cancel runs, and poll run status
• terraform_cloud.plans — fetch plan JSON, diffs, and summaries
• terraform_cloud.variables — read and set workspace variables (sensitive and non-sensitive)
• terraform_cloud.state — inspect state versions and download statefiles
• terraform_cloud.logs — retrieve run logs and apply output

Each tool accepts structured arguments and returns structured responses that an AI assistant can reason about and present to users.

Use Cases

1. Create a new workspace and run a plan

   • Human: “Create a new workspace named staging-api connected to our staging repo, run a plan, and show me the diff.”
   • Assistant flow:
     1. Call terraform_cloud.workspaces.create with organization, workspace name, VCS repo.
     2. Call terraform_cloud.runs.create (plan-only) for the new workspace.
     3. Call terraform_cloud.plans.fetch to retrieve the plan json/diff and present a summary to the user.

2. Rotate a sensitive API key in a workspace

   • Human: “Rotate the DB_PASSWORD variable in prod-db workspace and create a plan.”
   • Assistant flow:
     1. Call terraform_cloud.variables.set on workspace prod-db with sensitive flag.
     2. Trigger terraform_cloud.runs.create to plan the change.
     3. Return run-id and plan summary; ask for confirmation before apply.

3. Inspect a failed run and surface actionable errors

   • Human: “Why did run r-12345 fail?”
   • Assistant flow:
     1. Call terraform_cloud.runs.get to fetch run status and error reason.
     2. Call terraform_cloud.logs.fetch to collect relevant logs.
     3. Summarize root cause and suggest remediation steps.

4. Automate routine maintenance via an AI agent

   • Periodic prompts like “Run security drift scan across all workspaces” can be converted to enumerated runs and policy checks that run in Terraform Cloud, with results aggregated and presented.

Tips for Developers

• Treat the MCP server as the single integration point between your assistant and Terraform Cloud — keep authentication and audit logging centralized.
• Use workspace-level variables for secrets and mark them sensitive to avoid exposure in assistant output.
• When exposing the server to external assistants, enforce access controls and rate limits to prevent accidental destructive operations.
• Leverage plan JSON output to produce human-readable summaries rather than raw diffs.

For full implementation details, examples of the MCP tool schema, and deployment recipes, see the project’s repository: https://github.com/severity1/terraform-cloud-m