본문으로 건너뛰기
MCP 서버 전체 목록

Terraform MCP Server

  • 추천0
  • GitHub 별1.6K
  • 클라우드원격 연결라이선스MPL-2.0

HashiCorp 공식 MCP 서버. Terraform 레지스트리 조회와 HCP Terraform 워크스페이스 관리를 에이전트에 연결해요(원격 · Docker). MPL-2.0

원본:hashicorp/terraform-mcp-server

연결 · 설치 방법은 설치 탭에 정리했어요.

설명

Terraform MCP 서버

Terraform MCP 서버는 Terraform Registry와 HCP Terraform API와 매끄럽게 통합되는 Model Context Protocol(MCP) 서버로, 코드형 인프라(IaC) 개발에 고급 자동화와 상호작용 기능을 제공합니다.

특징

  • 두 가지 전송 방식: Stdio와 StreamableHTTP를 모두 지원하며 엔드포인트를 설정할 수 있습니다
  • Terraform Registry 통합: 공개 Terraform Registry API와 직접 통합해 프로바이더, 모듈, 정책을 다룹니다
  • HCP Terraform 및 Terraform Enterprise 지원: 워크스페이스 관리, 조직 · 프로젝트 목록, 비공개 레지스트리 접근을 모두 지원합니다
  • 워크스페이스 작업: 변수, 태그, 실행(run) 관리를 포함해 워크스페이스를 만들고, 고치고, 지웁 수 있습니다
  • 도구 사용을 모니터링하는 OTel 메트릭: OpenTelemetry 미터와 통합해 Streamable HTTP 모드에서 도구 호출량, 지연 시간, 실패를 추적합니다. 이 기능을 켜면 기본 HTTP 서버 메트릭도 내보냅니다

💡 보안 참고 쿼리에 따라 MCP 서버가 일부 Terraform 데이터를 MCP 클라이언트와 LLM에 노출할 수 있습니다. 신뢰할 수 없는 MCP 클라이언트나 LLM과 함께 쓰지 마세요.

💡 법적 참고 서드파티 MCP 클라이언트 · LLM의 사용은 그 MCP · LLM의 이용 약관에만 따릅니다. IBM은 서드파티 도구의 성능에 책임지지 않으며, 그 도구가 일으킨 문제는 지원하지 못할 수 있습니다.

💡 주의 MCP 서버가 내놓는 결과와 권장 사항은 쿼리, 모델, 연결된 MCP 클라이언트에 따라 동적으로 생성되고 달라질 수 있습니다. 적용하기 전에 조직의 보안 모범 사례, 비용 효율 목표, 규정 준수 요건에 맞는지 철저히 검토하세요.

준비물

  1. 컨테이너 환경에서 서버를 쓰려면 Docker가 설치되어 실행 중이어야 합니다.
  2. Model Context Protocol(MCP)을 지원하는 AI 어시스턴트를 설치하세요.

명령줄 옵션

환경 변수(주요 항목):

변수설명기본값
TFE_ADDRESSAPI 호출에 쓸 Terraform Enterprise/HCP Terraform 주소를 정합니다. 프로토콜을 포함해야 합니다(예: https://app.terraform.io). streamable-http 모드에서는 이것이 주소를 정하는 유일한 방법이며, 클라이언트가 헤더나 쿼리 매개변수로 정할 수 없습니다.선택
TFE_TOKENTerraform Enterprise API 토큰""(빈 값)
TF_MCP_QUERY_WORKSPACE사용자가 명시적 워크스페이스를 주지 않으면 검색/쿼리 도구가 쓰는 제안 소스 워크스페이스. 에이전트가 쿼리 워크플로 전에 정해진 소스를 확인합니다. 가져오기 대상과는 독립적입니다.미설정. TF_WORKSPACE로 대체
TF_MCP_IMPORT_WORKSPACE사용자가 명시적 대상을 주지 않으면 가져오기 도구가 쓰는 제안 가져오기 대상. 에이전트는 가져오기 도구를 부르기 전에 언제나 대상을 보여 주고 확인받아야 합니다.미설정. TF_WORKSPACE로 대체
TF_WORKSPACETF_MCP_QUERY_WORKSPACE가 없을 때의 소스 워크스페이스 기본값, TF_MCP_IMPORT_WORKSPACE가 없을 때의 가져오기 대상 기본값. 어느 쪽도 에이전트의 확인을 대신하지 못합니다.미설정
TF_CLOUD_ORGANIZATION명시적 조직이 없을 때 쓰는 제안 검색 소스 조직.미설정
TFE_SKIP_TLS_VERIFYHCP Terraform 또는 Terraform Enterprise의 TLS 검증을 건너뜁니다false
LOG_LEVEL로그 수준: trace, debug, info, warn, error, fatal, panicinfo
LOG_FORMAT로그 형식: text 또는 jsontext
TRANSPORT_MODEHTTP 전송을 켜려면 streamable-http로 둡니다stdio
TRANSPORT_HOSTHTTP 서버를 묶을 호스트127.0.0.1
TRANSPORT_PORTHTTP 서버 포트8080
MCP_ENDPOINTHTTP 서버 엔드포인트 경로/mcp
MCP_SESSION_MODE세션 모드: stateful 또는 statelessstateful
MCP_ALLOWED_ORIGINSCORS로 허용할 출처 목록(쉼표로 구분)""
MCP_CORS_MODECORS 모드: strict, development, disabledstrict
MCP_TLS_CERT_FILE / MCP_TLS_KEY_FILETLS 인증서 · 키 파일 경로. 로컬호스트가 아닌 배포에 필수""
MCP_RATE_LIMIT_GLOBAL전역 요청 속도 제한(형식 rps:burst)10:20
MCP_RATE_LIMIT_SESSION세션당 요청 속도 제한(형식 rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTHTTP 서버에 접근할 수 있는 HCP Terraform 조직 이름 목록(쉼표로 구분)""
MCP_FORWARD_CLIENT_IP클라이언트 IP를 X-Forwarded-For로 HCP Terraform / TFE에 넘깁니다. true로 켭니다false
ENABLE_TF_OPERATIONS명시적 승인이 필요한 도구를 켭니다false
OTEL_METRICS_ENABLEDOpenTelemetry로 도구 · 서버 메트릭을 켭니다false
# 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>]

지침(Instructions)

MCP 서버의 기본 지침은 cmd/terraform-mcp-server/instructions.md에 있습니다. 조직의 Terraform 관행과 맞지 않거나 서버가 부정확한 답을 내면 직접 쓴 지침으로 바꾸고 컨테이너나 바이너리를 다시 빌드하세요. 예시는 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 서버 도구에 관해서는 에이전트 모드 문서를 보세요.

로컬(Docker):

{
  "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": {
        "type": "http",
        "url": "https://mcp.terraform.io/mcp",
        "headers": {
          "Authorization": "Bearer <<TFE_TOKEN>>"
        }
      }
    }
  }
}

워크스페이스의 .vscode/mcp.json 파일에 mcp 키 없이 비슷한 예시를 적어도 됩니다. 다른 사람과 설정을 나눌 수 있습니다.

Cursor

Cursor 설정(~/.cursor/mcp.json) 또는 Settings → Cursor Settings → MCP에 다음을 추가하세요.

로컬(Docker):

{
  "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": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

Claude Desktop / Amazon Q Developer / Kiro CLI

Claude Desktop의 MCP 서버 도구는 사용자 문서를 보세요. Amazon Q Developer와 Kiro CLI의 MCP 서버 사용법도 참고하세요.

로컬(Docker):

{
  "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": {
      "url": "https://mcp.terraform.io/mcp",
      "headers": {
        "Authorization": "Bearer <<TFE_TOKEN>>"
      }
    }
  }
}

💡 참고 Claude Desktop은 설정 파일로 원격 MCP 서버를 설정할 수 없습니다. 대신 사용자 지정 커넥터를 쓰세요.

Claude Code

Claude Code에서 MCP 서버 도구를 추가하고 쓰는 방법은 사용자 문서를 보세요.

로컬:

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

원격:

claude mcp add terraform -s user -t http \
  --header "Authorization: Bearer <<TFE_TOKEN>>" \
  https://mcp.terraform.io/mcp

Codex CLI

💡 참고 인증된 HCP Terraform 또는 Terraform Enterprise 도구를 쓰려면 Docker 명령에 TFE_ADDRESS와 TFE_TOKEN을 더하세요.

로컬:

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

원격:

codex mcp add에는 사용자 지정 헤더를 위한 플래그가 없으므로 ~/.codex/config.toml에 서버를 추가하세요.

[mcp_servers.terraform]
url = "https://mcp.terraform.io/mcp"
http_headers = { "Authorization" = "Bearer <<TFE_TOKEN>>" }

Gemini 확장

보안을 위해 자격 증명을 직접 적지 말고, ~/.gemini/.env(~는 홈 또는 프로젝트 디렉터리)를 만들거나 고쳤 HCP Terraform 또는 Terraform Enterprise 자격 증명을 저장하세요.

# ~/.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 · OpenCode

Bob에서 MCP 쓰기와 OpenCode MCP 서버 문서를 보고 같은 방식의 로컬(Docker) · 원격 설정을 넣으세요. 예시는 저장소 README에 있습니다.

Kubernetes(Helm)

Kubernetes에 서버를 배포하는 Helm 차트는 helm/terraform-mcp-server에 있습니다.

소스에서 설치

최신 릴리스 버전을 쓰려면:

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

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

서버를 쓰기 전에 Docker 이미지를 로컬에서 빌드해야 합니다.

  1. 저장소를 복제합니다.
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
  1. Docker 이미지를 빌드합니다.
make docker-build
  1. 이렇게 하면 아래 설정에 쓸 로컬 Docker 이미지가 만들어집니다.
# stdio 모드로 실행
docker run -i --rm terraform-mcp-server:dev

# streamable-http 모드로 실행
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# 도구 필터링(선택)
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

💡 참고 Docker에서 실행할 때는 컨테이너 밖에서의 연결을 허용하도록 TRANSPORT_HOST=0.0.0.0으로 두세요.

  1. (선택) http 모드에서 연결을 시험합니다.
curl http://localhost:8080/health
  1. AI 어시스턴트에서 다음처럼 쓸 수 있습니다.
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

쓸 수 있는 도구

사용 가능한 도구와 리소스는 HashiCorp 공식 참조 문서에서 볼 수 있습니다.

도구 오류

HCP Terraform이나 TFE API 응답 때문에 도구가 실패하고 그 원인을 알아볼 수 있으면, 오류 글이 코드로 시작하고 결과의 _meta에 코드와 HTTP 상태가 담깁니다.

error_codehttp_status뜻
unauthorized401토큰이 유효하지 않거나 만료됨
not_found404리소스가 없거나 토큰으로 볼 수 없음
conflict409워크스페이스가 잠긴 상태이거나 잠기지 않았거나 안전하게 지울 수 없음

네트워크 오류나 API의 검증 오류 같은 다른 실패에는 코드가 붙지 않습니다. 토큰이 없으면 API를 부르기 전에 실패하므로 코드가 없습니다. 토큰 없는 요청을 HTTP 401로 거부하려면 MCP_REQUIRE_TOKEN=true로 두세요.

도구 필터링

--toolsets(묶음) 또는 --tools(개별)로 쓸 수 있는 도구를 제어합니다.

# 도구 묶음 켜기(기본: registry)
terraform-mcp-server --toolsets=registry,terraform

# 특정 도구만 켜기
terraform-mcp-server --tools=search_provider_docs,get_provider_details,list_workspaces

쓸 수 있는 도구 묶음: registry, registry-private, terraform, all, default. 개별 도구 이름은 pkg/toolsets/mapping.go를 보세요. 두 플래그를 함께 쓸 수 없습니다.

전송 방식 지원

1. Stdio 전송(기본)

JSON-RPC 메시지를 쓰는 표준 입출력 통신입니다. 로컬 개발과 MCP 클라이언트와의 직접 연동에 알맞습니다.

2. StreamableHTTP 전송

직접 HTTP 요청과 Server-Sent Events(SSE) 스트림을 모두 지원하는 최신 HTTP 기반 전송입니다. 원격 · 분산 환경에 권장하는 전송입니다.

  • 엔드포인트: http://{hostname}:8080/mcp
  • 상태 확인: http://{hostname}:8080/health
  • 환경 설정: TRANSPORT_MODE=http 또는 TRANSPORT_PORT=8080으로 켭니다
  • 조직 허용 목록: MCP_ORGANIZATION_ALLOWLIST 또는 --organization-allowlist에 허용할 HCP Terraform 조직 이름을 쉼표로 적습니다

세션 모드

StreamableHTTP 전송에서는 두 가지 세션 모드를 지원합니다.

  • Stateful 모드(기본): 요청 사이에 세션 상태를 유지해 맥락을 아는 작업이 가능합니다.
  • Stateless 모드: 요청을 서로 독립적으로 처리합니다. 고가용성 배포나 로드 밸런서를 쓸 때 유용합니다.

stateless를 켜려면 환경 변수를 설정하세요.

export MCP_SESSION_MODE=stateless

중앙 배포용 토큰 전달

MCP 서버를 여러 사용자용으로 중앙에서(StreamableHTTP 모드) 돌릴 때, 사용자마다 자기 Terraform 토큰을 HTTP 헤더로 넘겨 역할 기반 접근 제어(RBAC)를 적용할 수 있습니다. 서버 하나가 권한이 다른 여러 사용자를 처리합니다.

MCP_ORGANIZATION_ALLOWLIST를 설정하면 서버는 Authorization: Bearer <token>을 요구하고, 그 토큰으로 허용 목록의 조직 중 하나 이상에 접근할 수 있어야 요청을 받습니다. 조직 이름 비교는 대소문자를 구분하지 않습니다.

지원하는 헤더

헤더설명
TFE_TOKENTerraform API 토큰
Authorization: Bearer <token>표준 Bearer 인증을 쓰는 대안 방법

보안 고려 사항

  • 클라이언트가 TFE_ADDRESS를 정할 수 없습니다. streamable-http 모드에서 Terraform 주소는 서버 쪽 TFE_ADDRESS 환경 변수(또는 기본값)에서만 가져옵니다. 헤더나 쿼리 매개변수로 정하려는 요청은 403으로 거부됩니다.
  • 클라이언트가 TFE_SKIP_TLS_VERIFY를 정할 수 없습니다.
  • 토큰을 쿼리 매개변수로 넘기지 마세요. 서버는 그런 요청을 400 오류로 거부합니다.
  • 중앙 배포에서는 전송 중 토큰을 지키려면 항상 TLS(MCP_TLS_CERT_FILE/MCP_TLS_KEY_FILE)를 쓰세요.
  • MCP_ALLOWED_ORIGINS로 연결할 수 있는 클라이언트를 제한하세요.

중앙 배포 예시

# 서버를 중앙에서 시작(서버 쪽에는 토큰 없음)
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

사용자는 자기 토큰을 헤더로 넘겨 연결하고, 사용자별 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.4.1

대안: 바이너리를 직접 실행하세요. Docker를 허용하지 않는 환경이면 바이너리를 설치해 직접 실행할 수 있으며, 이 경우 시스템 인증서 저장소를 씁니다.

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

개발

준비물

  • Go(필요한 버전은 go.mod 파일 참고)
  • Docker(선택, 컨테이너 빌드용)

쓸 수 있는 Make 명령

명령설명
make build바이너리 빌드
make test모든 테스트 실행
make test-e2e종단 간(end-to-end) 테스트 실행
make docker-buildDocker 이미지 빌드
make run-httpHTTP 서버를 로컬에서 실행
make docker-run-httpDocker에서 HTTP 서버 실행
make test-httpHTTP 상태 확인 엔드포인트 테스트
make clean빌드 결과물 삭제
make help쓸 수 있는 모든 명령 보기

기여하기

  1. 저장소를 포크합니다
  2. 기능 브랜치를 만듭니다
  3. 변경을 합니다
  4. 테스트를 실행합니다
  5. 풀 리퀘스트를 보냅니다

더 알아보기

이 글은 README의 주요 절(특징, 설치, 도구 필터링, 전송 방식, 중앙 배포 · 보안, 문제 해결, 개발)을 다룹니다. 검색(Search) 도구 세트의 세부 동작, 클라이언트 IP 전달(X-Forwarded-For) 설정, 관측 지표 목록, 프로파일링은 저장소 README에서 확인하세요.

라이선스

이 프로젝트는 MPL-2.0 오픈소스 라이선스 조건으로 배포됩니다. 자세한 조항은 LICENSE 파일을 보세요.

보안

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

지원

버그 신고와 기능 요청은 GitHub에 이슈를 여세요. 일반 질문과 토론은 GitHub Discussion을 여세요.


저장소: hashicorp/terraform-mcp-server