stv-io/aws-terraform-mcp-server

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:

1. uv - Python package manager
2. Python 3.10+
3. Terraform CLI (for workflow execution)
4. Checkov (for security scanning)

For Docker usage:

1. 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 for commit message guidelines.

📄 License

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

🙏 Acknowledgments

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

📞 Support

For issues and questions:

• GitHub Issues
• Original AWS Labs Repository

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.