README.md•5.41 kB
# AWS Terraform MCP Server
[](https://github.com/stv-io/aws-terraform-mcp-server/pkgs/container/aws-terraform-mcp-server)
[](https://github.com/stv-io/aws-terraform-mcp-server)
[](https://opensource.org/licenses/Apache-2.0)
Docker containerized version of the [AWS Labs Terraform MCP Server](https://github.com/awslabs/mcp/tree/main/src/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)
```bash
# 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:
```json
{
"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:
```json
{
"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
```bash
# 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
```bash
# 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)
```bash
# Test the server directly using uv
python3 test_mcp_server.py
```
#### Unit Tests
```bash
# Run the comprehensive test suite
python3 -m pytest tests/ -v
```
### Using UV (Alternative)
```bash
# Install dependencies
uv sync
# Run the server
uv run awslabs.terraform-mcp-server
```
## 📋 Prerequisites
For local development:
1. [uv](https://docs.astral.sh/uv/getting-started/installation/) - 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](https://semver.org/) with automated releases based on [Conventional Commits](https://www.conventionalcommits.org/).
### 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](CONTRIBUTING.md) for commit message guidelines.
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Original implementation by [AWS Labs](https://github.com/awslabs/mcp)
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
- Uses [FastMCP](https://github.com/jlowin/fastmcp) framework
## 📞 Support
For issues and questions:
- [GitHub Issues](https://github.com/stv-io/aws-terraform-mcp-server/issues)
- [Original AWS Labs Repository](https://github.com/awslabs/mcp)
---
**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.