Terraform MCP Server

Terraform MCP Server

O Terraform MCP Server é um servidor Model Context Protocol (MCP) que fornece integração perfeita com as APIs do Terraform Registry, permitindo automação avançada e capacidades de interação para desenvolvimento de Infraestrutura como Código (IaC).

Funcionalidades

• Suporte a Transporte Duplo: Transportes Stdio e StreamableHTTP com endpoints configuráveis
• Integração com o Terraform Registry: Integração direta com APIs públicas do Terraform Registry para providers, módulos e políticas
• Suporte ao HCP Terraform e Terraform Enterprise: Gerenciamento completo de workspaces, listagem de organizações/projetos e acesso a registros privados
• Operações de Workspace: Criar, atualizar, excluir workspaces com suporte para variáveis, tags e gerenciamento de execuções
• Métricas OTel para monitoramento do uso de ferramentas: Integração com medidores de telemetria aberta para rastrear volume de chamadas de ferramentas, latência e falhas no modo HTTP Streamable. Também expõe métricas padrão do servidor HTTP quando esta funcionalidade está habilitada

Nota de Segurança: Dependendo da consulta, o servidor MCP pode expor certos dados do Terraform ao cliente MCP e ao LLM. Não use o servidor MCP com clientes MCP ou LLMs não confiáveis.

Nota Legal: O uso de um Cliente MCP/LLM de terceiros está sujeito exclusivamente aos termos de uso de tal MCP/LLM, e a IBM não é responsável pelo desempenho dessas ferramentas de terceiros. A IBM se isenta expressamente de quaisquer garantias e responsabilidades por Clientes MCP/LLMs de terceiros, e pode não ser capaz de fornecer suporte para resolver problemas causados por ferramentas de terceiros.

Atenção: As saídas e recomendações fornecidas pelo servidor MCP são geradas dinamicamente e podem variar com base na consulta, modelo e cliente MCP conectado. Os usuários devem revisar minuciosamente todas as saídas/recomendações para garantir que estejam alinhadas com as melhores práticas de segurança, metas de eficiência de custos e requisitos de conformidade da sua organização antes da implementação.

Pré-requisitos

1. Certifique-se de que o Docker esteja instalado e em execução para usar o servidor em um ambiente containerizado.
2. Instale um assistente de IA que suporte o Model Context Protocol (MCP).

Opções de Linha de Comando

Variáveis de Ambiente:

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

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--organization-allowlist <orgs-csv>] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

Instruções

As instruções padrão para o servidor MCP estão localizadas em cmd/terraform-mcp-server/instructions.md, se elas não parecerem apropriadas para as práticas de Terraform da sua organização ou se o servidor MCP estiver produzindo respostas imprecisas, substitua-as por suas próprias instruções e reconstrua o contêiner ou binário. Um exemplo de tal instrução está localizado em instructions/example-mcp-instructions.md

AGENTS.md essencialmente se comporta como READMEs para agentes de codificação: um local dedicado e previsível para fornecer o contexto e as instruções para ajudar os agentes de codificação de IA a trabalhar no seu projeto. Um arquivo AGENTS.md funciona com diferentes agentes de codificação. Um exemplo de tal instrução está localizado em instructions/example-AGENTS.md, para usá-lo, faça commit de um arquivo chamado AGENTS.md no diretório onde suas configurações do Terraform residem.

Instalação

Uso com Visual Studio Code

Adicione o seguinte bloco JSON ao seu arquivo de Configurações do Usuário (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

Mais sobre o uso de ferramentas de servidor MCP na documentação do modo agente do VS Code.

{
  "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:1.1.0"
        ]
      }
    },
    "inputs": [
      {
        "type": "promptString",
        "id": "tfe_token",
        "description": "Terraform API Token",
        "password": true
      },
      {
        "type": "promptString",
        "id": "tfe_address",
        "description": "Terraform Address",
        "password": false
      }
    ]
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "hashicorp/terraform-mcp-server:0.2.3"
        ]
      }
    }
  }
}

Opcionalmente, você pode adicionar um exemplo semelhante (ou seja, sem a chave mcp) a um arquivo chamado .vscode/mcp.json no seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outras pessoas.

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "TFE_TOKEN=${input:tfe_token}",
        "-e", "TFE_ADDRESS=${input:tfe_address}",
        "hashicorp/terraform-mcp-server:1.1.0"
      ]
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tfe_token",
      "description": "Terraform API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "tfe_address",
      "description": "Terraform Address",
      "password": false
    }
  ]
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Uso com Cursor

Adicione isto à sua configuração do Cursor (~/.cursor/mcp.json) ou via Configurações → Configurações do Cursor → MCP:

{
  "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:1.1.0"
      ]
    }
  }
}

{
  "servers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Uso com Claude Desktop / Amazon Q Developer / Kiro CLI

Mais sobre o uso de ferramentas de servidor MCP na documentação do usuário do Claude Desktop. Leia mais sobre o uso do servidor MCP no Amazon Q Developer e Kiro CLI.

{
  "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:1.1.0"
      ]
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ]
    }
  }
}

Uso com Claude Code

Mais sobre o uso e adição de ferramentas de servidor MCP na documentação do usuário do Claude Code

• Transporte Local (stdio)

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

• Transporte Remoto (streamable-http)

# Run server (example)
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 hashicorp/terraform-mcp-server

# Add to Claude Code
claude mcp add --transport http terraform http://localhost:8080/mcp

Uso com extensões Gemini

Por segurança, evite codificar suas credenciais, crie ou atualize ~/.gemini/.env (onde ~ é seu diretório home ou de projeto) para armazenar credenciais do HCP Terraform ou Terraform Enterprise

# ~/.gemini/.env
TFE_ADDRESS=your_tfe_address_here
TFE_TOKEN=your_tfe_token_here

Instale a extensão e execute o Gemini

gemini extensions install https://github.com/hashicorp/terraform-mcp-server
gemini

Uso com Bob IDE / Shell

Mais sobre o uso e adição de ferramentas de servidores MCP no Bob IDE ou Shell Usando MCP no Bob.

{
  "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:1.1.0"
      ],
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "hashicorp/terraform-mcp-server:0.2.3"
      ],
      "disabled": false
    }
  }
}

Instalar a partir do código fonte

Use a versão de lançamento mais recente:

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

Use o branch principal:

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

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server",
        "env": {
          "TFE_TOKEN": "<<TFE_TOKEN_HERE>>"
        },
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "terraform": {
        "type": "stdio",
        "command": "/path/to/terraform-mcp-server"
      }
    }
  }
}

Construindo a Imagem Docker localmente

Antes de usar o servidor, você precisa construir a imagem Docker localmente:

1. Clone o repositório:

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

2. Construa a imagem Docker:

make docker-build

3. Isso criará uma imagem Docker local que você pode usar na configuração a seguir.

# 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
docker run -i --rm terraform-mcp-server:dev --tools=search_providers,get_provider_details

Nota: Ao executar no Docker, você deve definir TRANSPORT_HOST=0.0.0.0 para permitir conexões de fora do contêiner.

4. (Opcional) Testar conexão no modo http

# Test the connection
curl http://localhost:8080/health

5. Você pode usá-lo no seu assistente de IA da seguinte forma:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

Ferramentas Disponíveis

Confira as ferramentas disponíveis aqui :link:

Recursos Disponíveis

Confira os recursos disponíveis aqui :link:

Métricas Disponíveis

Dois tipos de métricas são coletados. Primeiro, métricas padrão do servidor HTTP são adicionadas envolvendo o mux HTTP com otelhttp.NewHandler(...). Isso emite:

1. http.server.request.body.size
2. http.server.response.body.size
3. http.server.request.duration

Segundo, o servidor MCP registra métricas de ferramentas personalizadas em torno da execução de ferramentas usando hooks MCP (BeforeCallTool / AfterCallTool). Estas emitem:

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

Filtragem de Ferramentas

Controle quais ferramentas estão disponíveis usando --toolsets (grupos) ou --tools (individual):

# Enable tool groups (default: registry)
terraform-mcp-server --toolsets=registry,terraform

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

Conjuntos de ferramentas disponíveis: registry, registry-private, terraform, all, default. Consulte pkg/toolsets/mapping.go para nomes de ferramentas individuais. Não é possível usar ambos os sinalizadores juntos.

Suporte a Transporte

O Terraform MCP Server suporta múltiplos protocolos de transporte:

1. Transporte Stdio (Padrão)

Comunicação padrão de entrada/saída usando mensagens JSON-RPC. Ideal para desenvolvimento local e integração direta com clientes MCP.

2. Transporte StreamableHTTP

Transporte moderno baseado em HTTP que suporta tanto requisições HTTP diretas quanto streams de Server-Sent Events (SSE). Este é o transporte recomendado para configurações remotas/distribuídas.

Recursos:

• Endpoint: http://{hostname}:8080/mcp
• Verificação de Saúde: http://{hostname}:8080/health
• Configuração de Ambiente: Defina TRANSPORT_MODE=http ou TRANSPORT_PORT=8080 para habilitar
• Lista de Permissões de Organização: Defina MCP_ORGANIZATION_ALLOWLIST ou --organization-allowlist como uma lista CSV de nomes de organizações HCP Terraform permitidas

Modos de Sessão

O Terraform MCP Server suporta dois modos de sessão ao usar o transporte StreamableHTTP:

• Modo Stateful (Padrão): Mantém o estado da sessão entre requisições, permitindo operações sensíveis ao contexto.
• Modo Stateless: Cada requisição é processada independentemente, sem manter o estado da sessão, o que pode ser útil para implantações de alta disponibilidade ou ao usar balanceadores de carga.

Para habilitar o modo stateless, defina a variável de ambiente:

export MCP_SESSION_MODE=stateless

Passagem de Token para Implantações Centralizadas

Ao executar o servidor MCP centralmente (modo StreamableHTTP) para múltiplos usuários, cada usuário pode passar seu próprio token do Terraform via cabeçalhos HTTP para aplicação de RBAC. Isso permite que uma única instância de servidor atenda a múltiplos usuários com permissões diferentes.

Quando MCP_ORGANIZATION_ALLOWLIST ou --organization-allowlist está configurado, a lista de permissões deve ser uma lista CSV de nomes de organizações HCP Terraform. O servidor exige Authorization: Bearer <token> e rejeita requisições, a menos que esse token possa acessar pelo menos uma organização na lista CSV de permissões. O token bearer tem precedência se a requisição também incluir um cabeçalho TFE_TOKEN, garantindo que o token validado pela lista de permissões seja o token usado para as requisições da API do Terraform. A correspondência de nomes de organização não diferencia maiúsculas de minúsculas. Se o valor CSV configurado resultar em zero nomes de organização, o servidor encerra com um erro de lista de permissões de organização malformada.

Encaminhamento de IP do Cliente

Ao executar o servidor MCP centralmente atrás de um proxy ou balanceador de carga, você pode encaminhar o IP do cliente de origem para o HCP Terraform / TFE através do cabeçalho X-Forwarded-For. Isso está desabilitado por padrão e deve ser habilitado com MCP_FORWARD_CLIENT_IP=true.

Quando habilitado, o servidor obtém o IP do cliente de acordo com MCP_REMOTE_IP_METHOD:

Modelo de confiança

X-Forwarded-For e X-Real-IP são definidos por clientes e proxies intermediários, portanto, podem ser falsificados, a menos que um proxy confiável na frente do servidor os sobrescreva. Por esse motivo, o padrão é RemoteAddr, que confia apenas no par ao qual o servidor está diretamente conectado. Habilite X-Real-IP ou X-Forwarded-For somente quando o servidor estiver atrás de um proxy que você controla e que define esses cabeçalhos.

Saltos confiáveis

Ao usar X-Forwarded-For, MCP_XFF_TRUSTED_HOPS é o número de proxies que você opera entre o servidor e a internet. Os saltos são contados a partir da direita da cadeia, pois cada proxy anexa o endereço do qual recebeu a requisição e a entrada mais à direita é definida pelo proxy mais próximo do servidor. O servidor pula esse número de entradas confiáveis e pega a próxima à esquerda.

Por exemplo, com MCP_XFF_TRUSTED_HOPS=1 e um cabeçalho de 200.1.2.3, 10.1.1.10, o servidor seleciona 200.1.2.3. Com MCP_XFF_TRUSTED_HOPS=2 e 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1, ele seleciona 200.1.2.3. Se a contagem de saltos for maior que o número de entradas, ou a entrada selecionada não for um IP válido, o servidor recorre para RemoteAddr.

Definir a contagem de saltos muito baixa confiará em um valor fornecido pelo cliente; defini-la muito alta confiará em um endereço mais interno da sua própria infraestrutura. Defina-a para o número exato de proxies que você executa.

Limitações

• O servidor lê apenas o primeiro cabeçalho X-Forwarded-For em uma requisição. É válido que uma requisição carregue múltiplos cabeçalhos X-Forwarded-For, mas a biblioteca padrão do Go retorna apenas o primeiro, e o servidor não os une. Se sua cadeia de proxy emitir múltiplos cabeçalhos, configure-a para emitir um único cabeçalho X-Forwarded-For combinado.
• Endereços IPv4 e IPv6 são ambos suportados. Valores que não são IPs válidos são rejeitados e o servidor recorre para RemoteAddr.

Migrando de versões anteriores

Versões anteriores usavam o valor mais à esquerda de X-Forwarded-For quando o cabeçalho estava presente, sem configuração. Isso era inseguro, pois o valor mais à esquerda é o mais facilmente falsificável. O padrão agora é RemoteAddr. Se você executa o servidor atrás de um proxy e depende do encaminhamento de X-Forwarded-For para o HCP Terraform / TFE, defina MCP_REMOTE_IP_METHOD=X-Forwarded-For e MCP_XFF_TRUSTED_HOPS para o número de proxies que você opera.

Cabeçalhos Suportados

Exemplo: curl

# Using TFE_TOKEN header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "TFE_TOKEN: your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

# Using Authorization Bearer header
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-user-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

Considerações de Segurança

• TFE_ADDRESS não pode ser definido por clientes. No modo streamable-http, o endereço do Terraform é obtido apenas da variável de ambiente do lado do servidor TFE_ADDRESS (ou do padrão). Requisições que tentam definir TFE_ADDRESS via cabeçalho HTTP ou parâmetro de consulta são rejeitadas com um erro 403. Isso impede que um cliente redirecione requisições, e o token Authorization, para um servidor malicioso.
• Identificação de implantação hospedada: definir TF_MCP_SHARED_SECRET envia esse valor como o cabeçalho X-Tf-Mcp-Secret em cada requisição HCP Terraform / TFE, permitindo que o backend identifique requisições de uma implantação hospedada conhecida (por exemplo, para aplicar listas de permissões de IP). É um segredo estático enviado em um cabeçalho, portanto, use-o apenas sobre TLS e trate o valor como uma credencial.
• Nunca passe tokens em parâmetros de consulta - o servidor rejeitará tais requisições com um erro 400.
• Sempre use TLS (MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE) ao implantar centralmente para proteger os tokens em trânsito.
• Configure MCP_ALLOWED_ORIGINS para restringir quais clientes podem se conectar.

Exemplo de Implantação Centralizada

# Start server centrally (no token set server-side)
docker run -p 8080:8080 \
  -e TRANSPORT_MODE=streamable-http \
  -e TRANSPORT_HOST=0.0.0.0 \
  -e TFE_ADDRESS=https://tfe.company.com \
  -e MCP_TLS_CERT_FILE=/certs/server.pem \
  -e MCP_TLS_KEY_FILE=/certs/server-key.pem \
  -e MCP_ALLOWED_ORIGINS=https://ide.company.com \
  -e MCP_ORGANIZATION_ALLOWLIST=team-alpha,team-beta \
  -v /path/to/certs:/certs \
  hashicorp/terraform-mcp-server:1.1.0

Os usuários então se conectam com seus tokens individuais passados via cabeçalhos, permitindo a aplicação de RBAC por usuário.

Solução de Problemas

Proxy Corporativo / Inspeção TLS (Zscaler, etc.)

Se você estiver atrás de um proxy corporativo que realiza inspeção TLS (como Zscaler Internet Access), poderá ver erros de certificado:

tls: failed to verify certificate: x509: certificate signed by unknown authority

Solução: Monte o certificado CA corporativo no contêiner:

docker run -i --rm \
  -v /path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem \
  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
  hashicorp/terraform-mcp-server:1.1.0

Para configurações de cliente MCP:

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem",
        "-e", "SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem",
        "-e", "TFE_TOKEN=<>",
        "hashicorp/terraform-mcp-server:1.1.0"
      ]
    }
  }
}

Alternativa: Execute o binário diretamente

Se o Docker não for permitido em seu ambiente, você pode instalar e executar o binário do servidor diretamente, que usará o armazenamento de certificados do seu sistema:

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

Desenvolvimento

Pré-requisitos

• Go (verifique o arquivo go.mod para a versão específica)
• Docker (opcional, para builds de contêiner)

Comandos Make Disponíveis

Contribuindo

1. Faça um fork do repositório
2. Crie seu branch de funcionalidade
3. Faça suas alterações
4. Execute os testes
5. Envie um pull request

Licença

Este projeto está licenciado sob os termos da licença de código aberto MPL-2.0. Consulte o arquivo LICENSE para os termos completos.

Segurança

Para questões de segurança, entre em contato com security@hashicorp.com ou siga nossa política de segurança.

Suporte

Para relatórios de bugs e solicitações de funcionalidades, abra uma issue no GitHub.

Para perguntas gerais e discussões, abra uma GitHub Discussion.