Terraform MCP Server

Terraform MCP Server

O Terraform MCP Server é um servidor Model Context Protocol (MCP) que se integra perfeitamente às APIs do Terraform Registry e do HCP Terraform, permitindo automação avançada e recursos de interação para o desenvolvimento de Infrastructure as Code (IaC).

Sumário

Recursos

• Suporte a transporte duplo: Transportes Stdio e StreamableHTTP com endpoints configuráveis
• Integração com Terraform Registry: Integração direta com as APIs públicas do Terraform Registry para providers, módulos e políticas
• Suporte a 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 e excluir workspaces com suporte a variáveis, tags e gerenciamento de execuções
• Métricas OTel para monitoramento do uso de ferramentas: Integração com medidores de open telemetry para rastrear volume de chamadas de ferramentas, latência e falhas no modo Streamable HTTP. Também expõe métricas padrão do servidor HTTP quando esse recurso está habilitado

Nota de segurança: Dependendo da consulta, o servidor MCP pode expor determinados 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 desse MCP/LLM, e a IBM não é responsável pelo desempenho dessas ferramentas de terceiros. A IBM renuncia expressamente a todas e 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 de acordo com a consulta, o modelo e o cliente MCP conectado. Os usuários devem revisar minuciosamente todas as saídas/recomendações para garantir que estejam alinhadas com as práticas recomendadas 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 conteinerizado.
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 do servidor MCP estão localizadas em cmd/terraform-mcp-server/instructions.md; se elas não parecerem adequadas às práticas de Terraform da sua organização ou se o servidor MCP estiver produzindo respostas imprecisas, substitua-as pelas suas próprias instruções e recompile o contêiner ou binário. Um exemplo dessas instruções 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 contexto e instruções que ajudam agentes de codificação de IA a trabalhar no seu projeto. Um arquivo AGENTS.md funciona com diferentes agentes de codificação. Um exemplo dessas instruções está localizado em instructions/example-AGENTS.md; para usá-lo, faça commit de um arquivo chamado AGENTS.md no diretório onde residem suas configurações do Terraform.

Instalação

Uso com Visual Studio Code

Adicione o seguinte bloco JSON ao seu arquivo User Settings (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

Saiba mais sobre o uso das ferramentas do 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.3.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 workspace. 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.3.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 isso à sua configuração do Cursor (~/.cursor/mcp.json) ou via Settings → Cursor Settings → 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.3.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

Saiba mais sobre o uso de ferramentas do servidor MCP no Claude Desktop documentação do usuário. Leia mais sobre o uso do servidor MCP no Amazon Q Developer e no 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.3.0"
      ]
    }
  }
}

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

Uso com Claude Code

Saiba mais sobre o uso e a adição de ferramentas do servidor MCP no Claude Code documentação do usuário

• 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 Codex CLI

Saiba mais sobre o uso e a adição de ferramentas do servidor MCP no Codex CLI documentação do usuário.

Nota: Adicione TFE_ADDRESS e TFE_TOKEN aos comandos Docker para ferramentas autenticadas do HCP Terraform ou Terraform Enterprise.

• Transporte Local (stdio)

codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server

• Transporte Remoto (streamable-http)

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

# Add to Codex
codex mcp add terraform --url 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 pessoal 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

Saiba mais sobre o uso e a 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.3.0"
      ],
      "disabled": false
    }
  }
}

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

Kubernetes (Helm)

Um chart Helm para implantar o servidor no Kubernetes está disponível em helm/terraform-mcp-server.

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) Teste a 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 ao envolver 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 personalizadas de ferramentas em torno da execução de ferramentas usando hooks MCP (BeforeCallTool / AfterCallTool). Isso emite:

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 (individuais):

# 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 ambas as flags juntas.

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 fluxos 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ções: 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 cientes de contexto.
• Modo Stateless: Cada requisição é processada de forma independente, 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 Terraform via cabeçalhos HTTP para aplicação de RBAC. Isso permite que uma única instância do servidor atenda múltiplos usuários com diferentes permissões.

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 requisições à API Terraform. A correspondência de nomes de organizações não diferencia maiúsculas de minúsculas. Se o valor CSV configurado for analisado para zero nomes de organizações, o servidor sai com um erro de lista de permissões de organizações 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 HCP Terraform / TFE via cabeçalho X-Forwarded-For. Isso está desativado 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 peer 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 o número de saltos for maior que o número de entradas, ou se a entrada selecionada não for um IP válido, o servidor recorre a RemoteAddr.

Definir o número de saltos muito baixo confiará em um valor fornecido pelo cliente; defini-lo muito alto confiará em um endereço mais adentro da sua própria infraestrutura. Defina-o para o número exato de proxies que você opera.

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 proxies 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 a RemoteAddr.

Migrando de versões anteriores

Versões anteriores usavam o valor X-Forwarded-For mais à esquerda 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 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 Terraform é obtido apenas da variável de ambiente TFE_ADDRESS do lado do servidor (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 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 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.3.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), você pode 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.3.0

Para configurações de clientes 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.3.0"
      ]
    }
  }
}

Alternativa: Execute o binário diretamente

Se o Docker não for permitido no 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êineres)

Comandos Make Disponíveis

Contribuindo

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

Licença

Este projeto é 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 problemas 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 recursos, abra uma issue no GitHub.

Para perguntas gerais e discussões, abra uma Discussão no GitHub.