terraform-partner-mcp-server

Terraform MCP Server + Partner-Managed Resources

The Terraform MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Terraform Registry APIs, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

This fork extends the base server with Partner-Managed Resources - enabling AI-assisted security remediation through AWS Security Hub integration and HCP Terraform.

What's New: Partner-Managed Resources

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    PARTNER-MANAGED RESOURCES WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌──────────────┐                                      ┌──────────────┐         │
│  │ AWS Security │   Discover    ┌──────────────┐       │ HCP Terraform│         │
│  │     Hub      │──────────────▶│   MCP Server │──────▶│  (CLI-Driven │         │
│  │  (Findings)  │               │              │       │   Workspace) │         │
│  └──────────────┘               │  • Sync      │       └──────┬───────┘         │
│                                 │  • Analyze   │              │                  │
│  ┌──────────────┐               │  • Link      │              ▼                  │
│  │    Claude    │◀─────────────▶│  • Remediate │       ┌──────────────┐         │
│  │   Desktop    │   Converse    │              │       │     AWS      │         │
│  │  or CLI      │               └──────────────┘       │  Resources   │         │
│  └──────────────┘                                      │   (Fixed!)   │         │
│                                                        └──────────────┘         │
└─────────────────────────────────────────────────────────────────────────────────┘

Key Capabilities

• Security Finding Discovery: Pull findings from AWS Security Hub automatically
• Automatic ARN → Terraform Mapping: Discovers workspaces, parses state, and auto-links ARNs to Terraform addresses
• Automated Remediation: Generate and apply Terraform fixes through HCP Terraform
• CLI-Driven Workflow: Works with CLI-driven workspaces (configuration uploaded via API)

How Automatic Resource Mapping Works

When you provide your HCP Terraform org, the system automatically discovers and links resources:

sync_recommendations(terraform_org: "my-org")
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. DISCOVER WORKSPACES                                                   │
│    Lists all workspaces in your org (via HCP Terraform API)             │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. INDEX TERRAFORM STATE                                                 │
│    For each workspace, parses state and extracts cloud resource IDs:    │
│    - ARNs from aws_security_group, aws_instance, aws_s3_bucket, etc.    │
│    - Builds index: ARN → Terraform address                              │
│    Example: "arn:aws:ec2:...:sg-xxx" → "aws_security_group.web"         │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. SYNC & AUTO-LINK                                                      │
│    Fetches findings from Security Hub, matches ARNs to Terraform        │
│    Result: Each finding knows its Terraform resource automatically!     │
└─────────────────────────────────────────────────────────────────────────┘

No manual linking required! Just provide terraform_org and the system handles the mapping.

Supported Resource Mappings

The auto-discovery system supports the following AWS-to-Terraform resource mappings:

AWS Security Hub Type	Terraform Resource Type
AwsEc2Instance	aws_instance
AwsEc2SecurityGroup	aws_security_group
AwsEc2Volume	aws_ebs_volume
AwsEc2Vpc	aws_vpc
AwsEc2Subnet	aws_subnet
AwsEc2NetworkInterface	aws_network_interface
AwsS3Bucket	aws_s3_bucket
AwsIamUser	aws_iam_user
AwsIamRole	aws_iam_role
AwsIamPolicy	aws_iam_policy
AwsIamAccessKey	aws_iam_access_key
AwsLambdaFunction	aws_lambda_function
AwsRdsDbInstance	aws_db_instance
AwsRdsDbCluster	aws_rds_cluster
AwsKmsKey	aws_kms_key
AwsSecretsManagerSecret	aws_secretsmanager_secret
AwsSqsQueue	aws_sqs_queue
AwsSnsTopic	aws_sns_topic
AwsSnsSubscription	aws_sns_topic_subscription
AwsCloudFrontDistribution	aws_cloudfront_distribution
AwsElbLoadBalancer	aws_elb
AwsElbv2LoadBalancer	aws_lb
AwsApiGatewayRestApi	aws_api_gateway_rest_api
AwsDynamoDbTable	aws_dynamodb_table
AwsElasticsearchDomain	aws_elasticsearch_domain
AwsEksCluster	aws_eks_cluster
AwsEcsCluster	aws_ecs_cluster
AwsEcsService	aws_ecs_service

How Resources Are Matched: The system extracts cloud resource IDs from Terraform state and matches them to Security Hub findings using ARNs. For each resource type, these attributes are checked (in order):

Terraform Resource	ID Attributes (priority order)
aws_instance	arn, id
aws_s3_bucket	arn, bucket, id
aws_security_group	arn, id
aws_lambda_function	arn, function_name
aws_db_instance	arn, id, identifier
aws_iam_role	arn, id, name
aws_iam_user	arn, id, name
aws_kms_key	arn, key_id, id
aws_lb / aws_alb	arn, id
aws_autoscaling_group	arn, id, name
(others)	arn, id

CLI-Driven vs VCS-Driven Workspaces

This extension is designed for CLI-driven workspaces where:

• Terraform configuration is uploaded directly via the HCP Terraform API
• Runs are triggered programmatically (not through Git commits)
• The AI assistant manages the configuration lifecycle

CLI-Driven Workflow (Supported):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Download    │───▶│ Generate    │───▶│ Upload New  │───▶│ Create &    │
│ Current     │    │ Fix Code    │    │ Config      │    │ Apply Run   │
│ Config      │    │             │    │ Version     │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

VCS-Driven Workflow (Experimental - via GitHub PR):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Clone       │───▶│ Generate    │───▶│ Create PR   │───▶│ Merge &     │
│ Repository  │    │ Fix Code    │    │ on GitHub   │    │ Auto-Apply  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

Features

• Dual Transport Support: Both Stdio and StreamableHTTP transports with configurable endpoints
• Terraform Registry Integration: Direct integration with public Terraform Registry APIs for providers, modules, and policies
• HCP Terraform & Terraform Enterprise Support: Full workspace management, organization/project listing, and private registry access
• Workspace Operations: Create, update, delete workspaces with support for variables, tags, and run management
• Partner-Managed Resources: Security recommendation sync, analysis, and automated remediation

Security Note: At this stage, the MCP server is intended for local use only. If using the StreamableHTTP transport, always configure the MCP_ALLOWED_ORIGINS environment variable to restrict access to trusted origins only.

Security Note: Depending on the query, the MCP server may expose certain Terraform data to the MCP client and LLM. Do not use the MCP server with untrusted MCP clients or LLMs.

Caution: The outputs and recommendations provided by the MCP server are generated dynamically and may vary based on the query, model, and the connected MCP client. Users should thoroughly review all outputs/recommendations before implementation.

Quick Start (Partner-Managed Resources)

1. Build the Server

git clone <repository>
cd cc-partner-managed-resources
go build -o terraform-mcp-server ./cmd/terraform-mcp-server

2. Configure Claude Desktop

macOS: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "terraform": {
      "command": "/absolute/path/to/terraform-mcp-server",
      "args": ["--toolsets=partner,terraform"],
      "env": {
        "TFE_TOKEN": "your-hcp-terraform-token",
        "TFE_ADDRESS": "https://app.terraform.io",
        "AWS_ACCESS_KEY_ID": "your-aws-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret-key",
        "AWS_REGION": "us-west-2",
        "ENABLE_TF_OPERATIONS": "true"
      }
    }
  }
}

3. Use with Claude

User: "Configure AWS Security Hub for us-west-2"
User: "Sync security recommendations"
User: "Show me HIGH severity findings"
User: "Remediate the SSH security group finding"

Available Toolsets

Toolset	Description	Use Case
registry	Public Terraform Registry	Search providers, modules, documentation
registry-private	Private registry access	Private modules and providers
terraform	HCP Terraform operations	Workspace management, runs, state
partner	Partner-managed resources	Security recommendations, remediation
all	All toolsets combined	Full functionality
default	registry + terraform	Standard usage

Partner Toolset - Tools Reference

Configuration Tools

Tool	Description
configure_aws_security_hub	Set up AWS Security Hub as recommendation source
configure_aws_recommendations	Set up AWS Compute Optimizer (cost optimization)
list_recommendation_sources	List all configured sources

Discovery Tools

Tool	Description
sync_recommendations	Pull latest findings from configured sources
list_recommendations	Query with filters (severity, category, status)
get_recommendation	Get full details of a specific finding

Remediation Tools

Tool	Description
link_recommendation_resource	Map finding to Terraform resource address
remediate_recommendation	Generate fix and apply through HCP Terraform
preview_remediation	Preview changes without applying
apply_remediation	Apply previously previewed changes

Resource Management Tools

Tool	Description
register_resources	Register Terraform resources with partner registry
resolve_resources	Resolve ARNs to Terraform addresses
get_resource_state	Get current Terraform state for a resource
get_drift_status	Check for infrastructure drift

Tool Workflow Sequence

The partner tools follow a specific workflow sequence:

1. Configure     →  2. Sync         →  3. Review       →  4. Remediate
   ─────────        ──────────         ────────          ─────────────
   configure_aws_   sync_              list_             remediate_
   security_hub     recommendations    recommendations   recommendation
   (or configure_   (with terraform_   get_              (or preview_ +
   aws_             org for auto-      recommendation    apply_
   recommendations) discovery)                           remediation)

Notes:

• sync_recommendations with terraform_org auto-discovers and links resources
• Manual linking via link_recommendation_resource is only needed if auto-discovery fails (e.g., unrecognized ARN format)
• Use preview_remediation to review changes before applying

Environment Variables

Core Variables

Variable	Description	Default
TFE_ADDRESS	HCP Terraform or TFE address	https://app.terraform.io
TFE_TOKEN	Terraform Enterprise API token	(required)
TFE_SKIP_TLS_VERIFY	Skip TLS verification	false
ENABLE_TF_OPERATIONS	Enable Terraform operations	false

Partner Variables

Variable	Description	Default
AWS_ACCESS_KEY_ID	AWS access key	(required for partner)
AWS_SECRET_ACCESS_KEY	AWS secret key	(required for partner)
AWS_REGION	AWS region	us-west-2
GITHUB_TOKEN	GitHub token (for VCS workflow)	(optional)

Transport Variables

Variable	Description	Default
TRANSPORT_MODE	stdio or streamable-http	stdio
TRANSPORT_HOST	HTTP server host	127.0.0.1
TRANSPORT_PORT	HTTP server port	8080
MCP_ENDPOINT	HTTP endpoint path	/mcp

Testing

E2E Test Suite

A comprehensive E2E test environment is available in test-e2e-remediation/:

cd test-e2e-remediation/scripts

# Configure credentials
cp env.sh.template env.sh
# Edit env.sh with your credentials

# Run MCP CLI test (no Claude Desktop required)
source env.sh
python3 mcp-full-test.py

# Or run the full infrastructure test
./01-setup-workspace.sh
./02-deploy-infrastructure.sh
# ... (see test-e2e-remediation/README.md)

See test-e2e-remediation/README.md for complete testing documentation including:

• MCP CLI testing (no Claude Desktop)
• Claude Desktop testing with step-by-step prompts
• Verified test results

Example: Security Remediation Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Configure                                                            │
│ > configure_aws_security_hub(region: "us-west-2", categories: ["security"]) │
│ ✓ Configured AWS Security Hub (us-west-2)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 2: Sync with Auto-Discovery                                             │
│ > sync_recommendations(terraform_org: "my-org")  ← Enables auto-linking!    │
│ ✓ Synced 20 findings from AWS Security Hub                                  │
│ ✓ Indexed 5 workspaces with 47 resources                                    │
│ ✓ Auto-linked 3 recommendations to Terraform                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 3: List (already linked!)                                               │
│ > list_recommendations(severity: "high", managed_only: true)                │
│ ✓ [HIGH] EC2.19 - Security group allows SSH from 0.0.0.0/0                  │
│   Resource: sg-096b4ac3e0159bed6                                            │
│   Terraform: aws_security_group.vulnerable  ← Auto-linked!                  │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 4: Remediate (no manual linking needed!)                                │
│ > remediate_recommendation(rec_id, confirm: true)                           │
│ ✓ Run created: run-wQvXTgsbk9MXQd5r                                         │
│ ✓ Status: applied                                                            │
│ ✓ SSH CIDR changed: 0.0.0.0/0 → 10.0.0.0/8                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Project Structure

cc-partner-managed-resources/
├── cmd/terraform-mcp-server/     # Main server binary
├── pkg/
│   ├── partner/                  # Partner package
│   │   ├── recommendation_types.go    # Data structures
│   │   ├── recommendation_source.go   # Source interface
│   │   ├── recommendation_registry.go # Session storage
│   │   ├── code_generator.go          # Terraform fix generation
│   │   └── sources/
│   │       └── aws_security_hub.go    # AWS Security Hub source
│   ├── tools/partner/            # MCP tool implementations
│   ├── toolsets/                 # Toolset definitions
│   └── client/                   # Session and client management
├── test-e2e-remediation/         # E2E test environment
│   ├── terraform/                # Vulnerable test infrastructure
│   ├── scripts/                  # Test scripts (CLI + Claude Desktop)
│   └── docs/                     # Test documentation and results
└── README.md                     # This file

Code Generation

HCL-Based Modification (Current Implementation)

The remediation code generator (pkg/partner/code_generator.go) uses HashiCorp's hclwrite library for proper HCL AST manipulation:

// Parse HCL content
file, diags := hclwrite.ParseConfig([]byte(content), "main.tf", hcl.InitialPos)

// Find and modify resource blocks
resourceBlock := findResourceBlock(body, "aws_security_group", "vulnerable")

// Find nested blocks with criteria matching (e.g., ingress with from_port=22)
for _, block := range body.Blocks() {
    if block.Type() == "ingress" && blockMatchesCriteria(block, {"from_port": "22"}) {
        block.Body().SetAttributeValue("cidr_blocks", cty.ListVal(...))
    }
}

// Output preserves formatting
return string(file.Bytes())

What works well:

• Proper HCL AST parsing and serialization
• Nested block handling (ingress/egress rules, metadata_options, versioning_configuration)
• Selective block modification (e.g., only SSH ingress, not HTTPS)
• Type-aware attribute setting (lists, booleans, strings, numbers)
• Preserved formatting and structure
• Fallback to string replacement if HCL parsing fails

Supported Fixes:

Check ID	Finding	Fix Applied
EC2.19	SSH open to 0.0.0.0/0	cidr_blocks = ["10.0.0.0/8"]
EC2.18	RDP open to 0.0.0.0/0	cidr_blocks = ["10.0.0.0/8"]
EC2.3/EC2.7	EBS/EC2 not encrypted	encrypted = true
EC2.8	IMDSv2 not required	http_tokens = "required"
S3.14	Versioning disabled	status = "Enabled"
Cost	Instance oversized	instance_type = "m5.large"

Future Improvements

1. Pluggable Fix Strategies

   • Define fix patterns as configuration/plugins
   • Allow custom remediation rules per organization
   • Support for organization-specific security policies

2. Dry-run Validation

   • Run terraform validate on generated code before upload
   • Catch syntax errors before creating a run

3. Additional Recommendation Sources

   • AWS Trusted Advisor (requires Business support plan)
   • AWS Compute Optimizer (cost optimization - partially implemented)
   • Third-party security platforms

Underutilized Features

These features are implemented but may not be commonly used:

Feature	Tool/Parameter	Description
managed_only	list_recommendations	Filter to only Terraform-managed resources
force_refresh	sync_recommendations	Force re-sync even if recently synced
preview_only	remediate_recommendation	Preview changes without applying
VCS workflow	apply_remediation	Create GitHub PR instead of direct upload

---

Original Terraform MCP Server Documentation

Prerequisites

1. Ensure Docker is installed and running to use the server in a containerized environment.
2. Install an AI assistant that supports the Model Context Protocol (MCP).

Command Line Options

# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]

Instructions

Default instructions for the MCP server is located in cmd/terraform-mcp-server/instructions.md, if those do not seem appropriate for your organization's Terraform practices or if the MCP server is producing inaccurate responses, please replace them with your own instructions and rebuild the container or binary.

Installation

Usage with Visual Studio Code

Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "servers": {
      "terraform": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "TFE_TOKEN=${input:tfe_token}",
          "-e", "TFE_ADDRESS=${input:tfe_address}",
          "hashicorp/terraform-mcp-server"
        ]
      }
    }
  }
}

Usage with Claude Desktop

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server"
      ]
    }
  }
}

Usage with Claude Code

claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

Install from source

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest

Building the Docker Image locally

git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
make docker-build

# Run in stdio mode
docker run -i --rm terraform-mcp-server:dev

# Run in streamable-http mode
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# Filter tools (optional)
docker run -i --rm terraform-mcp-server:dev --toolsets=registry,terraform

Available Tools

Check out available tools here

Tool Filtering

Control which tools are available using --toolsets (groups) or --tools (individual):

# Enable tool groups
terraform-mcp-server --toolsets=registry,terraform,partner

# Enable specific tools only
terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces

Transport Support

1. Stdio Transport (Default)

Standard input/output communication using JSON-RPC messages. Ideal for local development.

2. StreamableHTTP Transport

Modern HTTP-based transport supporting both direct HTTP requests and Server-Sent Events (SSE) streams.

• Endpoint: http://{hostname}:8080/mcp
• Health Check: http://{hostname}:8080/health

Development

Prerequisites

• Go (check go.mod file for specific version)
• Docker (optional, for container builds)

Available Make Commands

Command	Description
make build	Build the binary
make test	Run all tests
make test-e2e	Run end-to-end tests
make docker-build	Build Docker image
make run-http	Run HTTP server locally
make clean	Remove build artifacts

License

This project is licensed under the terms of the MPL-2.0 open source license. Please refer to LICENSE file for the full terms.

Support

For bug reports and feature requests, please open an issue on GitHub.