Azure Terraform MCP Server

A Model Context Protocol (MCP) server for Azure Terraform operations, providing intelligent assistance for infrastructure as code development with Azure resources.

Overview

This MCP server provides support for Azure Terraform development, including:

• Azure provider documentation retrieval of AzureRM, AzAPI and Azure Verified Module(AVM)
• HCL code validation and static analysis with TFLint
• Security scanning and compliance checking
• Best practices guidance
• Resource analysis and recommendations

Features

🔍 Documentation & Discovery

• Azure Provider Docs: Comprehensive documentation retrieval for AzureRM resources
• AzAPI Schema: Schema lookup for Azure API resources
• Azure Verified Modules (AVM): Discovery and documentation for verified Terraform modules including module listings, versions, variables, and outputs
• Resource Documentation: Detailed arguments, attributes, and examples

🛡️ Security & Compliance

• Security Scanning: Built-in security rule validation for Azure resources
• Azure Verified Modules (AVM) Policies: Integration with Conftest and Azure Policy Library AVM for comprehensive policy validation
• Best Practices: Azure-specific best practices and recommendations

🔧 Development Tools

• Unified Terraform Commands: Single tool to execute all Terraform commands (init, plan, apply, destroy, validate, fmt) plus full state management (list, show, mv, rm, pull, push)
• State Management: Safe resource renaming and state manipulation using proper Terraform commands
• HCL Validation: Syntax validation and error reporting for Terraform code
• HCL Formatting: Automatic code formatting for Terraform configurations
• TFLint Integration: Static analysis with TFLint including Azure ruleset support for Terraform workspaces
• Azure Export for Terraform (aztfexport): Export existing Azure resources to Terraform configuration and state
• Code Cleanup Workflow: Transform exported code into production-ready infrastructure as code

📋 Schema & Provider Analysis

• Terraform Schema Query: Query fine-grained schema information for any Terraform provider
• Provider Item Discovery: List all available resources, data sources, and functions for providers
• Provider Support Discovery: Find which providers are available for analysis
• Dynamic Schema Loading: Support for all providers in the Terraform Registry

🔍 Golang Source Code Analysis

• Golang Namespace Discovery: Find available golang packages for source code analysis
• Version/Tag Support: Query specific versions of provider source code
• Source Code Retrieval: Read golang source code for functions, methods, types, and variables
• Terraform Implementation Analysis: Understand how Terraform resources are implemented in Go

🚀 Integration

• MCP Protocol: Full Model Context Protocol compliance for AI assistant integration
• FastMCP Framework: Built on FastMCP for high-performance async operations

Quick Start

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "tf-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name", "tf-mcp-server-instance",
        "-v", "${workspaceFolder}:/workspace",
        "-e", "ARM_CLIENT_ID=${env:ARM_CLIENT_ID}",
        "-e", "ARM_CLIENT_SECRET=${env:ARM_CLIENT_SECRET}",
        "-e", "ARM_SUBSCRIPTION_ID=${env:ARM_SUBSCRIPTION_ID}",
        "-e", "ARM_TENANT_ID=${env:ARM_TENANT_ID}",
        "-e", "LOG_LEVEL=INFO",
        "ghcr.io/liuwuliuyun/tf-mcp-server:latest"
      ],
      "env": {
        "ARM_CLIENT_ID": "${env:ARM_CLIENT_ID}",
        "ARM_CLIENT_SECRET": "${env:ARM_CLIENT_SECRET}",
        "ARM_SUBSCRIPTION_ID": "${env:ARM_SUBSCRIPTION_ID}",
        "ARM_TENANT_ID": "${env:ARM_TENANT_ID}"
      }
    }
  }
}

Need More Options?

For detailed installation instructions including:

• 🐳 Docker with Azure authentication
• ⚡ UV installation for development
• 🐍 Traditional Python setup
• 🔧 Optional tool installation
• ⚙️ Configuration options

👉 See the complete Installation Guide

Configuration

For detailed configuration options including environment variables, configuration files, and Azure authentication setup, see the Installation Guide.

Telemetry

This tool collects anonymous usage telemetry to help improve quality and performance. We collect:

• ✅ Tool usage counts and performance metrics
• ✅ Anonymous user ID (randomly generated UUID)
• ✅ Error types and success rates

We DO NOT collect:

• ❌ Personal information or identifiers
• ❌ File paths, resource names, or configuration content
• ❌ Azure subscription IDs or credentials

Opt-Out

Telemetry is optional and can be disabled anytime:

# Disable telemetry via environment variable
export TELEMETRY_ENABLED=false

Or add to your .vscode/mcp.json:

{
  "servers": {
    "tf-mcp-server": {
      "env": {
        "TELEMETRY_ENABLED": "false"
      }
    }
  }
}

📖 For complete details, see Telemetry Documentation

Available Tools

The server provides comprehensive tools across multiple categories. For complete tool reference with examples, see the API Reference.

Documentation Tools

• get_azurerm_provider_documentation: Retrieve specific AzureRM resource or data source documentation with optional argument/attribute lookup
• get_azapi_provider_documentation: Retrieve AzAPI resource schemas and documentation
• get_avm_modules: Retrieve all available Azure Verified Modules with descriptions and source information
• get_avm_latest_version: Get the latest version of a specific Azure Verified Module
• get_avm_versions: Get all available versions of a specific Azure Verified Module
• get_avm_variables: Retrieve the input variables schema for a specific AVM module version
• get_avm_outputs: Retrieve the output definitions for a specific AVM module version

Terraform Command Tools

• run_terraform_command: Execute Terraform CLI commands (init, plan, apply, destroy, validate, fmt) and state management operations (list, show, mv, rm, pull, push) inside a workspace folder

Security & Validation Tools

• check_conftest_installation: Check Conftest installation status and get version information
• run_conftest_workspace_validation: Validate Terraform files in a workspace folder against Azure security policies
• run_conftest_workspace_plan_validation: Validate Terraform plan files against Azure security policies
• check_tflint_installation: Check TFLint installation status and get version information
• run_tflint_workspace_analysis: Run TFLint static analysis on workspace folders containing Terraform files

Azure Export Tools

• check_aztfexport_installation: Check Azure Export for Terraform (aztfexport) installation status and version
• export_azure_resource: Export a single Azure resource to Terraform configuration using aztfexport
• export_azure_resource_group: Export an entire Azure resource group and its resources to Terraform configuration
• export_azure_resources_by_query: Export Azure resources using Azure Resource Graph queries to Terraform configuration
• get_aztfexport_config: Get aztfexport configuration settings
• set_aztfexport_config: Set aztfexport configuration settings

Coverage Audit Tools

• audit_terraform_coverage: Audit Terraform coverage of Azure resources, compare state against Azure Resource Graph to identify gaps, orphaned resources, and get actionable recommendations

Best Practices Tools

• get_azure_best_practices: Get comprehensive Azure and Terraform best practices for specific resources and actions
  • Supports AzureRM 4.x and AzAPI 2.x recommendations
  • Special "code-cleanup" action for aztfexport workflow
  • Clear guidance on variables vs locals
  • State management best practices
  • Security hardening recommendations
• check_azurerm_feature_availability: Verify if specific features are supported by the AzureRM provider
  • Guides AI to compare AzureRM and AzAPI documentation
  • Recommends using AzAPI when features are missing from AzureRM

📚 Documentation

For comprehensive guides and examples:

• 📖 Documentation Index - Complete documentation overview
• 🚀 Installation Guide - Setup instructions for all platforms
• 🔧 Configuration Guide - Environment variables and settings
• 📋 API Reference - Complete tool reference with examples
• ❓ Troubleshooting - Common issues and solutions

Feature Guides

• Azure Documentation Tools - AzureRM, AzAPI, and AVM documentation access
• Terraform Commands - Execute Terraform operations and state management
• Terraform State Management - Safe resource renaming and state operations
• Terraform Coverage Audit - Audit Terraform coverage and identify infrastructure gaps
• Security Policies - Policy-based validation and compliance
• TFLint Integration - Static analysis for Terraform code quality
• Conftest AVM Validation - Policy-based security validation with Azure policies
• Azure Export Integration - Export existing Azure resources to Terraform
• Azure Best Practices - Get Azure-specific recommendations and code cleanup guidance

Example Usage

For complete examples and workflows, see the API Reference.

Project Structure

tf-mcp-server/
├── src/                            # Main source code
│   ├── data/                       # Data files and schemas
│   │   └── azapi_schemas_v2.6.1.json # AzAPI resource schemas
│   └── tf_mcp_server/              # Core package
│       ├── __init__.py
│       ├── __main__.py             # Package entry point  
│       ├── launcher.py             # Server launcher
│       ├── core/                   # Core functionality
│       │   ├── __init__.py
│       │   ├── azapi_schema_generator.py # AzAPI schema generation
│       │   ├── config.py           # Configuration management
│       │   ├── models.py           # Data models and types
│       │   ├── server.py           # FastMCP server with all MCP tools
│       │   ├── terraform_executor.py # Terraform execution utilities
│       │   └── utils.py            # Shared utility functions
│       └── tools/                  # Tool implementations
│           ├── __init__.py
│           ├── avm_docs_provider.py     # Azure Verified Modules documentation provider
│           ├── azapi_docs_provider.py   # AzAPI documentation provider  
│           ├── azurerm_docs_provider.py # AzureRM documentation provider
│           ├── aztfexport_runner.py     # Azure Export for Terraform (aztfexport) integration
│           ├── conftest_avm_runner.py   # Conftest policy validation runner
│           ├── coverage_auditor.py      # Terraform coverage audit tool
│           ├── terraform_runner.py      # Terraform command execution and state management
│           └── tflint_runner.py         # TFLint static analysis runner
├── tests/                          # Test suite
│   ├── __init__.py
│   ├── conftest.py                 # Test configuration
│   ├── test_*.py                   # Unit tests
│   └── integration/                # Integration tests
├── tfsample/                       # Sample Terraform configurations
├── workspace/                      # Default workspace directory for operations
├── policy/                         # Security and compliance policies
│   ├── avmsec/                     # Azure security policies (AVM Security)
│   ├── Azure-Proactive-Resiliency-Library-v2/ # Azure resiliency policies  
│   └── common/                     # Common policy utilities
├── docs/                           # Comprehensive documentation
├── examples/                       # Usage examples and workflows
├── pyproject.toml                  # Project configuration (UV/pip)
├── uv.lock                         # UV dependency lockfile
├── Dockerfile                      # Docker container configuration
├── docker-compose.yml              # Docker Compose setup
├── README.md                       # This file
└── CONTRIBUTE.md                   # Development and contribution guide

Troubleshooting

For comprehensive troubleshooting including:

• Docker and VS Code MCP setup issues
• Azure authentication problems
• Tool installation and configuration
• Performance optimization
• Platform-specific solutions

👉 See the detailed Troubleshooting Guide

Quick Debug

Enable debug logging:

{
  "mcpServers": {
    "tf-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${workspaceFolder}:/workspace",
        "-e", "LOG_LEVEL=DEBUG",
        "-e", "MCP_DEBUG=true",
        "ghcr.io/liuwuliuyun/tf-mcp-server:latest"
      ]
    }
  }
}

Check logs for detailed information and error diagnosis.

Contributing

We welcome contributions! For development setup, coding standards, and detailed contribution guidelines:

👉 See the complete Contributing Guide

Quick Start for Contributors

1. Fork the repository
2. Set up development environment (see CONTRIBUTE.md)
3. Create a feature branch: git checkout -b feature/your-feature
4. Make changes with tests
5. Run tests and formatting: pytest && black src/ tests/
6. Submit a pull request

License

This project is licensed under the MIT License. See LICENSE file for details.

Support

For issues and questions:

• Create an issue in the repository
• Check the troubleshooting section above
• Review existing documentation and tests

Related Projects

• FastMCP Framework
• Azure Terraform Provider
• AzAPI Provider
• Model Context Protocol