Terraform MCP Server

Servidor MCP do Terraform

O Servidor MCP do Terraform é um servidor do Model Context Protocol (MCP) que se integra perfeitamente às APIs do Terraform Registry e do HCP Terraform, permitindo recursos avançados de automação e 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 o Terraform Registry: Integração direta com as 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 ao registro privado
• 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 se isenta expressamente de todas e quaisquer garantias e responsabilidades por Clientes MCP/LLMs de terceiros, e pode não conseguir oferecer 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, no modelo e no 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, as metas de eficiência de custos e os requisitos de conformidade de 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 ofereça suporte ao 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 pelas suas próprias instruções e recompile o contêiner ou binário. Um exemplo de tal instrução está localizado em instructions/example-mcp-instructions.md

AGENTS.md funciona essencialmente como READMEs para agentes de codificação: um local dedicado e previsível para fornecer o contexto e as instruções que ajudam agentes de IA de codificação 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 o 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 como usar as 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.4.1"
        ]
      }
    },
    "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.4.1"
      ]
    }
  },
  "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 o Cursor

Adicione isto à 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.4.1"
      ]
    }
  }
}

{
  "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 como usar as ferramentas do servidor MCP no Claude Desktop na documentação do usuário. Leia mais sobre como usar o 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.4.1"
      ]
    }
  }
}

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

Uso com Claude Code

Saiba mais sobre como usar e adicionar ferramentas do servidor MCP no Claude Code na 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 como usar e adicionar ferramentas do servidor MCP no Codex CLI na 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 do Gemini

Por segurança, evite codificar suas credenciais diretamente; crie ou atualize ~/.gemini/.env (onde ~ é seu diretório home ou de projeto) para armazenar as 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 como usar e adicionar ferramentas de servidores MCP no Bob IDE ou Shell em 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.4.1"
      ],
      "disabled": false
    }
  }
}

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

Kubernetes (Helm)

Um Helm chart 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 mais recente do release:

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

Use o branch main:

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_provider_docs,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 do 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_provider_docs,get_provider_details,list_workspaces

Conjuntos de ferramentas disponíveis: registry, registry-private, terraform, all, default. Consulte pkg/toolsets/mapping.go para nomes individuais de ferramentas. 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 integridade: 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 com estado (Padrão): Mantém o estado da sessão entre requisições, permitindo operações com reconhecimento de contexto.
• Modo sem estado: 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 sem estado, defina a variável de ambiente:

export MCP_SESSION_MODE=stateless

Passagem de token para implantações centralizadas

Ao executar o servidor MCP de forma centralizada (modo StreamableHTTP) para vários 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 do servidor atenda vários 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 de permissões CSV. 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 do Terraform. A correspondência de nomes de organizações não diferencia maiúsculas de minúsculas. Se o valor CSV configurado for analisado como zero nomes de organizações, o servidor encerra com um erro de lista de permissões de organizações malformada.

Encaminhamento de IP do cliente

Ao executar o servidor MCP de forma centralizada atrás de um proxy ou balanceador de carga, você pode encaminhar o IP do cliente de origem para o HCP Terraform / TFE por meio do cabeçalho X-Forwarded-For. Isso fica 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 à 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. Alguns balanceadores de carga, incluindo os Application Load Balancers da AWS, não definem X-Real-IP, portanto, com eles, o cabeçalho vem diretamente do cliente e não deve ser usado.

Saltos confiáveis

Ao usar X-Forwarded-For, defina MCP_XFF_TRUSTED_HOPS como o número de proxies que você opera à frente do servidor. Cada proxy acrescenta o endereço de onde recebeu a requisição, não o seu próprio endereço, portanto o IP do cliente é a entrada que está a essa quantidade de posições a partir da direita. Tudo à esquerda dela foi enviado pelo cliente e pode ser falsificado.

Por exemplo, atrás de um único balanceador de carga como um AWS ALB, defina MCP_XFF_TRUSTED_HOPS=1. Um cabeçalho 198.51.100.7 é resolvido para 198.51.100.7, e um cabeçalho 1.2.3.4, 198.51.100.7, em que o cliente enviou 1.2.3.4 por conta própria, também é resolvido para 198.51.100.7. Com MCP_XFF_TRUSTED_HOPS=2 e 1.2.3.4, 198.51.100.7, 10.0.0.5, o servidor seleciona 198.51.100.7. Se a contagem 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 a contagem de saltos muito alta fará com que um valor fornecido pelo cliente seja confiado; defini-la muito baixa selecionará um endereço da sua própria infraestrutura. Defina-a como o número exato de proxies que você executa.

Limitações

• Se uma requisição carregar vários cabeçalhos X-Forwarded-For, o servidor os une em ordem antes de selecionar uma entrada. Cabeçalho X-Forwarded-For.
• 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 mais à esquerda de X-Forwarded-For quando o cabeçalho estava presente, sem nenhuma 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 de X-Forwarded-For ser encaminhado para o HCP Terraform / TFE, defina MCP_REMOTE_IP_METHOD=X-Forwarded-For e MCP_XFF_TRUSTED_HOPS como 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 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 ao 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 de forma centralizada 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.4.1

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 o 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.4.1

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.4.1"
      ]
    }
  }
}

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, o 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 (consulte 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 sua branch de recurso
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 obter 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 recursos, abra uma issue no GitHub.

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