Terraform MCP Server

Terraform MCP Server

Terraform MCP Server는 Model Context Protocol (MCP) 서버로, Terraform Registry API와의 원활한 통합을 제공하여 Infrastructure as Code (IaC) 개발을 위한 고급 자동화 및 상호 작용 기능을 지원합니다.

기능

• 이중 전송 지원: 구성 가능한 엔드포인트를 갖춘 Stdio 및 StreamableHTTP 전송 방식 모두 지원
• Terraform Registry 통합: 공개 Terraform Registry API와 직접 통합하여 프로바이더, 모듈, 정책에 접근
• HCP Terraform 및 Terraform Enterprise 지원: 전체 워크스페이스 관리, 조직/프로젝트 목록 조회, 비공개 레지스트리 접근 지원
• 워크스페이스 운영: 변수, 태그, 실행 관리를 지원하는 워크스페이스 생성, 업데이트, 삭제
• 도구 사용량 모니터링을 위한 OTel 메트릭: Streamable HTTP 모드에서 도구 호출량, 지연 시간, 실패를 추적하기 위한 OpenTelemetry 미터 통합. 이 기능이 활성화되면 기본 HTTP 서버 메트릭도 노출합니다.

보안 참고 사항: 쿼리에 따라 MCP 서버가 특정 Terraform 데이터를 MCP 클라이언트 및 LLM에 노출할 수 있습니다. 신뢰할 수 없는 MCP 클라이언트나 LLM과 함께 MCP 서버를 사용하지 마십시오.

법적 참고 사항: 타사 MCP 클라이언트/LLM 사용은 해당 MCP/LLM의 이용 약관에만 적용되며, IBM은 이러한 타사 도구의 성능에 대해 책임지지 않습니다. IBM은 타사 MCP 클라이언트/LLM에 대한 모든 보증 및 책임을 명시적으로 부인하며, 타사 도구로 인해 발생하는 문제를 해결하기 위한 지원을 제공하지 못할 수 있습니다.

주의: MCP 서버가 제공하는 출력 및 권장 사항은 동적으로 생성되며 쿼리, 모델, 연결된 MCP 클라이언트에 따라 달라질 수 있습니다. 사용자는 구현 전에 모든 출력/권장 사항을 철저히 검토하여 조직의 보안 모범 사례, 비용 효율성 목표 및 규정 준수 요구 사항에 부합하는지 확인해야 합니다.

사전 요구 사항

1. 컨테이너화된 환경에서 서버를 사용하려면 Docker가 설치되어 실행 중인지 확인하십시오.
2. Model Context Protocol (MCP)을 지원하는 AI 어시스턴트를 설치하십시오.

명령줄 옵션

환경 변수:

# 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>]

지침

MCP 서버의 기본 지침은 cmd/terraform-mcp-server/instructions.md에 있습니다. 이것이 조직의 Terraform 사례에 적합하지 않거나 MCP 서버가 부정확한 응답을 생성하는 경우, 자체 지침으로 교체하고 컨테이너 또는 바이너리를 다시 빌드하십시오. 이러한 지침의 예는 instructions/example-mcp-instructions.md에 있습니다.

AGENTS.md은 기본적으로 코딩 에이전트를 위한 README 역할을 합니다. AI 코딩 에이전트가 프로젝트에서 작업하는 데 도움이 되는 컨텍스트와 지침을 제공하는 전용의 예측 가능한 장소입니다. 하나의 AGENTS.md 파일이 여러 코딩 에이전트와 함께 작동합니다. 이러한 지침의 예는 instructions/example-AGENTS.md에 있으며, 이를 사용하려면 Terraform 구성이 있는 디렉터리에 AGENTS.md이라는 파일을 커밋하십시오.

설치

Visual Studio Code에서 사용하기

VS Code의 사용자 설정(JSON) 파일에 다음 JSON 블록을 추가하십시오. Ctrl + Shift + P을 누르고 Preferences: Open User Settings (JSON)을 입력하면 됩니다.

VS Code의 에이전트 모드 문서에서 MCP 서버 도구 사용에 대해 자세히 알아보십시오.

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

선택적으로, 작업 영역의 .vscode/mcp.json이라는 파일에 유사한 예제(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
    }
  ]
}

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

Cursor에서 사용하기

Cursor 구성(~/.cursor/mcp.json) 또는 설정 → 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"
      ]
    }
  }
}

Claude Desktop / Amazon Q Developer / Kiro CLI에서 사용하기

Claude Desktop 사용자 문서에서 MCP 서버 도구 사용에 대해 자세히 알아보십시오. Amazon Q Developer 및 Kiro CLI에서 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"
      ]
    }
  }
}

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

Claude Code에서 사용하기

Claude Code 사용자 문서에서 MCP 서버 도구 사용 및 추가에 대해 자세히 알아보십시오.

• 로컬 (stdio) 전송

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

• 원격 (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

Gemini 확장 프로그램에서 사용하기

보안을 위해 자격 증명을 하드코딩하지 말고, HCP Terraform 또는 Terraform Enterprise 자격 증명을 저장하기 위해 ~/.gemini/.env (여기서 ~는 홈 또는 프로젝트 디렉터리)을 생성하거나 업데이트하십시오.

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

확장 프로그램 설치 및 Gemini 실행

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

Bob IDE / Shell에서 사용하기

Bob IDE 또는 Shell에서 MCP 서버 도구 사용 및 추가에 대해 자세히 알아보십시오 Bob에서 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"
      ],
      "disabled": false
    }
  }
}

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

소스에서 설치하기

최신 릴리스 버전을 사용하십시오:

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

메인 브랜치를 사용하십시오:

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"
      }
    }
  }
}

로컬에서 Docker 이미지 빌드하기

서버를 사용하기 전에 로컬에서 Docker 이미지를 빌드해야 합니다:

1. 리포지토리 복제:

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

2. Docker 이미지 빌드:

make docker-build

3. 이렇게 하면 다음 구성에서 사용할 수 있는 로컬 Docker 이미지가 생성됩니다.

# 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

참고: Docker에서 실행할 때는 컨테이너 외부에서의 연결을 허용하도록 TRANSPORT_HOST=0.0.0.0을 설정해야 합니다.

4. (선택 사항) http 모드에서 연결 테스트

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

5. 다음과 같이 AI 어시스턴트에서 사용할 수 있습니다:

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

사용 가능한 도구

사용 가능한 도구 확인하기 :link:

사용 가능한 리소스

사용 가능한 리소스 확인하기 :link:

사용 가능한 메트릭

두 종류의 메트릭이 수집됩니다. 첫째, otelhttp.NewHandler(...)로 HTTP mux를 래핑하여 표준 HTTP 서버 메트릭이 추가됩니다. 이는 다음을 내보냅니다:

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

둘째, MCP 서버는 MCP 훅(BeforeCallTool / AfterCallTool)을 사용하여 도구 실행에 대한 사용자 정의 도구 메트릭을 기록합니다. 이는 다음을 내보냅니다:

1. mcp_tool_calls_total
2. mcp_tool_errors_total
3. mcp_tool_duration_seconds

도구 필터링

--toolsets (그룹) 또는 --tools (개별)을 사용하여 사용 가능한 도구를 제어합니다:

# 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

사용 가능한 도구 세트: registry, registry-private, terraform, all, default. 개별 도구 이름은 pkg/toolsets/mapping.go을 참조하세요. 두 플래그를 함께 사용할 수 없습니다.

전송 지원

Terraform MCP 서버는 여러 전송 프로토콜을 지원합니다:

1. Stdio 전송 (기본값)

JSON-RPC 메시지를 사용하는 표준 입출력 통신입니다. 로컬 개발 및 MCP 클라이언트와의 직접 통합에 이상적입니다.

2. StreamableHTTP 전송

직접 HTTP 요청과 서버 전송 이벤트(SSE) 스트림을 모두 지원하는 최신 HTTP 기반 전송 방식입니다. 원격/분산 환경에 권장되는 전송 방식입니다.

기능:

• 엔드포인트: http://{hostname}:8080/mcp
• 상태 확인: http://{hostname}:8080/health
• 환경 설정: TRANSPORT_MODE=http 또는 TRANSPORT_PORT=8080을 설정하여 활성화
• 조직 허용 목록: MCP_ORGANIZATION_ALLOWLIST 또는 --organization-allowlist를 허용된 HCP Terraform 조직 이름의 CSV 목록으로 설정

세션 모드

Terraform MCP 서버는 StreamableHTTP 전송 사용 시 두 가지 세션 모드를 지원합니다:

• 상태 유지 모드 (기본값): 요청 간 세션 상태를 유지하여 컨텍스트 인식 작업을 가능하게 합니다.
• 상태 비저장 모드: 각 요청이 세션 상태를 유지하지 않고 독립적으로 처리되므로, 고가용성 배포나 로드 밸런서 사용 시 유용할 수 있습니다.

상태 비저장 모드를 활성화하려면 환경 변수를 설정하세요:

export MCP_SESSION_MODE=stateless

중앙 집중식 배포를 위한 토큰 전달

여러 사용자를 위해 MCP 서버를 중앙에서 실행(StreamableHTTP 모드)할 때, 각 사용자는 RBAC 적용을 위해 자신의 Terraform 토큰을 HTTP 헤더를 통해 전달할 수 있습니다. 이를 통해 단일 서버 인스턴스가 서로 다른 권한을 가진 여러 사용자에게 서비스를 제공할 수 있습니다.

MCP_ORGANIZATION_ALLOWLIST 또는 --organization-allowlist이 구성된 경우, 허용 목록은 HCP Terraform 조직 이름의 CSV 목록이어야 합니다. 서버는 Authorization: Bearer <token>를 요구하며, 해당 토큰이 CSV 허용 목록에 있는 하나 이상의 조직에 접근할 수 없는 경우 요청을 거부합니다. 요청에 TFE_TOKEN 헤더도 포함된 경우 베어러 토큰이 우선하므로, 허용 목록에 의해 검증된 토큰이 Terraform API 요청에 사용되는 토큰이 됩니다. 조직 이름 일치는 대소문자를 구분하지 않습니다. 구성된 CSV 값이 0개의 조직 이름으로 구문 분석되면 서버는 잘못된 조직 허용 목록 오류와 함께 종료됩니다.

클라이언트 IP 전달

프록시 또는 로드 밸런서 뒤에서 MCP 서버를 중앙에서 실행할 때, X-Forwarded-For 헤더를 통해 원본 클라이언트의 IP를 HCP Terraform / TFE로 전달할 수 있습니다. 이 기능은 기본적으로 비활성화되어 있으며 MCP_FORWARD_CLIENT_IP=true로 활성화해야 합니다.

활성화되면 서버는 MCP_REMOTE_IP_METHOD에 따라 클라이언트 IP를 가져옵니다:

신뢰 모델

X-Forwarded-For 및 X-Real-IP은 클라이언트와 중간 프록시에 의해 설정되므로, 서버 앞의 신뢰할 수 있는 프록시가 이를 덮어쓰지 않는 한 스푸핑될 수 있습니다. 이러한 이유로 기본값은 RemoteAddr이며, 이는 서버가 직접 연결된 피어만 신뢰합니다. 서버가 이러한 헤더를 설정하는 사용자 제어 프록시 뒤에 있는 경우에만 X-Real-IP 또는 X-Forwarded-For를 활성화하세요.

신뢰할 수 있는 홉

X-Forwarded-For 사용 시, MCP_XFF_TRUSTED_HOPS은 서버와 인터넷 사이에서 운영하는 프록시의 수입니다. 각 프록시는 요청을 받은 주소를 추가하고 가장 오른쪽 항목은 서버에 가장 가까운 프록시에 의해 설정되므로, 홉은 체인의 오른쪽부터 계산됩니다. 서버는 신뢰할 수 있는 항목을 그 수만큼 건너뛰고 왼쪽에 있는 다음 항목을 선택합니다.

예를 들어, MCP_XFF_TRUSTED_HOPS=1 및 200.1.2.3, 10.1.1.10 헤더가 있는 경우 서버는 200.1.2.3를 선택합니다. MCP_XFF_TRUSTED_HOPS=2 및 108.0.0.1, 200.1.2.3, 10.1.1.10, 192.168.0.1의 경우 200.1.2.3를 선택합니다. 홉 수가 항목 수보다 크거나 선택한 항목이 유효한 IP가 아닌 경우 서버는 RemoteAddr로 폴백합니다.

홉 수를 너무 낮게 설정하면 클라이언트 제공 값을 신뢰하게 되고, 너무 높게 설정하면 자체 인프라 내의 더 안쪽 주소를 신뢰하게 됩니다. 운영하는 프록시의 정확한 수로 설정하세요.

제한 사항

• 서버는 요청에서 첫 번째 X-Forwarded-For 헤더만 읽습니다. 요청이 여러 X-Forwarded-For 헤더를 전달하는 것은 유효하지만, Go의 표준 라이브러리는 첫 번째 헤더만 반환하며 서버는 이를 결합하지 않습니다. 프록시 체인이 여러 헤더를 내보내는 경우, 단일 결합 X-Forwarded-For 헤더를 내보내도록 구성하세요.
• IPv4 및 IPv6 주소가 모두 지원됩니다. 유효한 IP가 아닌 값은 거부되며 서버는 RemoteAddr로 폴백합니다.

이전 버전에서 마이그레이션

이전 버전에서는 헤더가 있을 때 가장 왼쪽 X-Forwarded-For 값을 구성 없이 사용했습니다. 가장 왼쪽 값이 가장 스푸핑하기 쉬우므로 이는 안전하지 않았습니다. 이제 기본값은 RemoteAddr입니다. 프록시 뒤에서 서버를 실행하고 X-Forwarded-For이 HCP Terraform / TFE로 전달되는 데 의존하는 경우, MCP_REMOTE_IP_METHOD=X-Forwarded-For 및 MCP_XFF_TRUSTED_HOPS를 운영하는 프록시 수로 설정하세요.

지원되는 헤더

예시: 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",...}'

보안 고려 사항

• TFE_ADDRESS는 클라이언트가 설정할 수 없습니다. streamable-http 모드에서 Terraform 주소는 서버 측 TFE_ADDRESS 환경 변수(또는 기본값)에서만 가져옵니다. HTTP 헤더 또는 쿼리 매개변수를 통해 TFE_ADDRESS을 설정하려는 요청은 403 오류와 함께 거부됩니다. 이렇게 하면 클라이언트가 요청과 Authorization 토큰을 악의적인 서버로 리디렉션하는 것을 방지할 수 있습니다.
• 절대 토큰을 쿼리 매개변수로 전달하지 마세요 - 서버는 이러한 요청을 400 오류와 함께 거부합니다.
• 중앙에 배포할 때는 항상 TLS(MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE)를 사용하여 전송 중인 토큰을 보호하세요.
• MCP_ALLOWED_ORIGINS을 구성하여 연결할 수 있는 클라이언트를 제한하세요.

중앙 집중식 배포 예시

# 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

그런 다음 사용자는 헤더를 통해 전달된 개별 토큰으로 연결하여 사용자별 RBAC 적용을 활성화합니다.

문제 해결

회사 프록시 / TLS 검사 (Zscaler 등)

TLS 검사를 수행하는 회사 프록시(예: Zscaler Internet Access) 뒤에 있는 경우 인증서 오류가 발생할 수 있습니다:

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

해결 방법: 회사 CA 인증서를 컨테이너에 마운트하세요:

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

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

대안: 바이너리를 직접 실행

환경에서 Docker가 허용되지 않는 경우 서버 바이너리를 직접 설치하고 실행할 수 있으며, 이 경우 시스템의 인증서 저장소를 사용합니다:

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

개발

사전 요구 사항

• Go (특정 버전은 go.mod 파일 확인)
• Docker (컨테이너 빌드용, 선택 사항)

사용 가능한 Make 명령

기여

1. 리포지토리 포크
2. 기능 브랜치 생성
3. 변경 사항 적용
4. 테스트 실행
5. 풀 리퀘스트 제출

라이선스

이 프로젝트는 MPL-2.0 오픈 소스 라이선스 조건에 따라 라이선스가 부여됩니다. 전체 조건은 LICENSE 파일을 참조하세요.

보안

보안 문제는 security@hashicorp.com으로 문의하거나 보안 정책을 따르세요.

지원

버그 신고 및 기능 요청은 GitHub에서 이슈를 열어주세요.

일반적인 질문과 토론은 GitHub Discussion을 열어주세요.