AWS Terraform MCP Server

Docker containerized version of the AWS Labs Terraform MCP Server - a Model Context Protocol (MCP) server for Terraform on AWS best practices, infrastructure as code patterns, and security compliance with Checkov.

🚀 Quick Start

Using Docker (Recommended)

# Pull and run the latest image
docker run --rm --interactive ghcr.io/stv-io/aws-terraform-mcp-server:latest

Using with MCP Clients

Windsurf IDE

Add to your Windsurf MCP settings:

{
  "name": "AWS Terraform MCP Server",
  "command": "docker",
  "args": [
    "run", "--rm", "--interactive",
    "--env", "FASTMCP_LOG_LEVEL=ERROR",
    "ghcr.io/stv-io/aws-terraform-mcp-server:latest"
  ],
  "env": {},
  "disabled": false,
  "autoApprove": []
}

Cursor IDE

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "aws-terraform-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "--interactive",
        "--env", "FASTMCP_LOG_LEVEL=ERROR",
        "ghcr.io/stv-io/aws-terraform-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

🛠️ Features

Tools Available

ExecuteTerraformCommand - Run Terraform commands (init, plan, validate, apply, destroy)
ExecuteTerragruntCommand - Run Terragrunt workflows with advanced features
SearchAwsProviderDocs - Search AWS provider documentation
SearchAwsccProviderDocs - Search AWSCC provider documentation
SearchSpecificAwsIaModules - Access AWS-IA GenAI modules (Bedrock, OpenSearch, SageMaker, Streamlit)
RunCheckovScan - Security and compliance scanning with Checkov
SearchUserProvidedModule - Analyze Terraform Registry modules

Resources Available

terraform_development_workflow - Security-focused development process guide
terraform_aws_provider_resources_listing - Comprehensive AWS provider resources catalog
terraform_awscc_provider_resources_listing - AWSCC provider resources catalog
terraform_aws_best_practices - AWS Terraform best practices guidance

🔧 Development

Building Locally

# Clone the repository
git clone https://github.com/stv-io/aws-terraform-mcp-server.git
cd aws-terraform-mcp-server

# Build the Docker image
docker build -t aws-terraform-mcp-server .

# Run locally
docker run --rm --interactive aws-terraform-mcp-server

Testing

Local Docker Testing

# Test the locally built Docker image
python3 test_docker_mcp.py

# Test the published Docker image from GHCR
sed 's|aws-terraform-mcp-server:latest|ghcr.io/stv-io/aws-terraform-mcp-server:latest|g' test_docker_mcp.py > test_published.py
python3 test_published.py

Direct Server Testing (without Docker)

# Test the server directly using uv
python3 test_mcp_server.py

Unit Tests

# Run the comprehensive test suite
python3 -m pytest tests/ -v

Using UV (Alternative)

# Install dependencies
uv sync

# Run the server
uv run awslabs.terraform-mcp-server

📋 Prerequisites

For local development:

uv - Python package manager
Python 3.10+
Terraform CLI (for workflow execution)
Checkov (for security scanning)

For Docker usage:

Docker or compatible container runtime

🔒 Security Considerations

Follow structured development workflow with integrated validation and security scanning
Review all Checkov warnings and fix security issues when possible
Use AWSCC provider for consistent API behavior and better security defaults
Conduct independent assessment before applying changes to production environments

🔄 Versioning

This project uses Semantic Versioning with automated releases based on Conventional Commits.

Available Tags

latest - Latest stable release
v1.2.3 - Specific version
v1.2 - Latest patch of minor version
v1 - Latest minor of major version

See CONTRIBUTING.md for commit message guidelines.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Original implementation by AWS Labs
Built on the Model Context Protocol
Uses FastMCP framework

📞 Support

For issues and questions:

Note: This is a containerized distribution of the AWS Labs Terraform MCP Server. All credit for the core functionality goes to the AWS Labs team.