Terraform MCP Server
- 추천0
- GitHub 별1.6K
- 클라우드원격 연결라이선스MPL-2.0
HashiCorp 공식 MCP 서버. Terraform 레지스트리 조회와 HCP Terraform 워크스페이스 관리를 에이전트에 연결해요(원격 · Docker). MPL-2.0
연결 · 설치 방법은 설치 탭에 정리했어요.
설명
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 클라이언트에 따라 동적으로 생성되고 달라질 수 있습니다. 적용하기 전에 조직의 보안 모범 사례, 비용 효율 목표, 규정 준수 요건에 맞는지 철저히 검토하세요.
준비물
- 컨테이너 환경에서 서버를 쓰려면 Docker가 설치되어 실행 중이어야 합니다.
- Model Context Protocol(MCP)을 지원하는 AI 어시스턴트를 설치하세요.
명령줄 옵션
환경 변수(주요 항목):
| 변수 | 설명 | 기본값 |
|---|---|---|
TFE_ADDRESS | API 호출에 쓸 Terraform Enterprise/HCP Terraform 주소를 정합니다. 프로토콜을 포함해야 합니다(예: https://app.terraform.io). streamable-http 모드에서는 이것이 주소를 정하는 유일한 방법이며, 클라이언트가 헤더나 쿼리 매개변수로 정할 수 없습니다. | 선택 |
TFE_TOKEN | Terraform Enterprise API 토큰 | ""(빈 값) |
TF_MCP_QUERY_WORKSPACE | 사용자가 명시적 워크스페이스를 주지 않으면 검색/쿼리 도구가 쓰는 제안 소스 워크스페이스. 에이전트가 쿼리 워크플로 전에 정해진 소스를 확인합니다. 가져오기 대상과는 독립적입니다. | 미설정. TF_WORKSPACE로 대체 |
TF_MCP_IMPORT_WORKSPACE | 사용자가 명시적 대상을 주지 않으면 가져오기 도구가 쓰는 제안 가져오기 대상. 에이전트는 가져오기 도구를 부르기 전에 언제나 대상을 보여 주고 확인받아야 합니다. | 미설정. TF_WORKSPACE로 대체 |
TF_WORKSPACE | TF_MCP_QUERY_WORKSPACE가 없을 때의 소스 워크스페이스 기본값, TF_MCP_IMPORT_WORKSPACE가 없을 때의 가져오기 대상 기본값. 어느 쪽도 에이전트의 확인을 대신하지 못합니다. | 미설정 |
TF_CLOUD_ORGANIZATION | 명시적 조직이 없을 때 쓰는 제안 검색 소스 조직. | 미설정 |
TFE_SKIP_TLS_VERIFY | HCP Terraform 또는 Terraform Enterprise의 TLS 검증을 건너뜁니다 | false |
LOG_LEVEL | 로그 수준: trace, debug, info, warn, error, fatal, panic | info |
LOG_FORMAT | 로그 형식: text 또는 json | text |
TRANSPORT_MODE | HTTP 전송을 켜려면 streamable-http로 둡니다 | stdio |
TRANSPORT_HOST | HTTP 서버를 묶을 호스트 | 127.0.0.1 |
TRANSPORT_PORT | HTTP 서버 포트 | 8080 |
MCP_ENDPOINT | HTTP 서버 엔드포인트 경로 | /mcp |
MCP_SESSION_MODE | 세션 모드: stateful 또는 stateless | stateful |
MCP_ALLOWED_ORIGINS | CORS로 허용할 출처 목록(쉼표로 구분) | "" |
MCP_CORS_MODE | CORS 모드: strict, development, disabled | strict |
MCP_TLS_CERT_FILE / MCP_TLS_KEY_FILE | TLS 인증서 · 키 파일 경로. 로컬호스트가 아닌 배포에 필수 | "" |
MCP_RATE_LIMIT_GLOBAL | 전역 요청 속도 제한(형식 rps:burst) | 10:20 |
MCP_RATE_LIMIT_SESSION | 세션당 요청 속도 제한(형식 rps:burst) | 5:10 |
MCP_ORGANIZATION_ALLOWLIST | HTTP 서버에 접근할 수 있는 HCP Terraform 조직 이름 목록(쉼표로 구분) | "" |
MCP_FORWARD_CLIENT_IP | 클라이언트 IP를 X-Forwarded-For로 HCP Terraform / TFE에 넘깁니다. true로 켭니다 | false |
ENABLE_TF_OPERATIONS | 명시적 승인이 필요한 도구를 켭니다 | false |
OTEL_METRICS_ENABLED | OpenTelemetry로 도구 · 서버 메트릭을 켭니다 | 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 이미지를 로컬에서 빌드해야 합니다.
- 저장소를 복제합니다.
git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
- Docker 이미지를 빌드합니다.
make docker-build
- 이렇게 하면 아래 설정에 쓸 로컬 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으로 두세요.
- (선택) http 모드에서 연결을 시험합니다.
curl http://localhost:8080/health
- AI 어시스턴트에서 다음처럼 쓸 수 있습니다.
{
"mcpServers": {
"terraform": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"terraform-mcp-server:dev"
]
}
}
}
쓸 수 있는 도구
사용 가능한 도구와 리소스는 HashiCorp 공식 참조 문서에서 볼 수 있습니다.
도구 오류
HCP Terraform이나 TFE API 응답 때문에 도구가 실패하고 그 원인을 알아볼 수 있으면, 오류 글이 코드로 시작하고 결과의 _meta에 코드와 HTTP 상태가 담깁니다.
error_code | http_status | 뜻 |
|---|---|---|
unauthorized | 401 | 토큰이 유효하지 않거나 만료됨 |
not_found | 404 | 리소스가 없거나 토큰으로 볼 수 없음 |
conflict | 409 | 워크스페이스가 잠긴 상태이거나 잠기지 않았거나 안전하게 지울 수 없음 |
네트워크 오류나 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_TOKEN | Terraform 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-build | Docker 이미지 빌드 |
make run-http | HTTP 서버를 로컬에서 실행 |
make docker-run-http | Docker에서 HTTP 서버 실행 |
make test-http | HTTP 상태 확인 엔드포인트 테스트 |
make clean | 빌드 결과물 삭제 |
make help | 쓸 수 있는 모든 명령 보기 |
기여하기
- 저장소를 포크합니다
- 기능 브랜치를 만듭니다
- 변경을 합니다
- 테스트를 실행합니다
- 풀 리퀘스트를 보냅니다
더 알아보기
이 글은 README의 주요 절(특징, 설치, 도구 필터링, 전송 방식, 중앙 배포 · 보안, 문제 해결, 개발)을 다룹니다. 검색(Search) 도구 세트의 세부 동작, 클라이언트 IP 전달(X-Forwarded-For) 설정, 관측 지표 목록, 프로파일링은 저장소 README에서 확인하세요.
라이선스
이 프로젝트는 MPL-2.0 오픈소스 라이선스 조건으로 배포됩니다. 자세한 조항은 LICENSE 파일을 보세요.
보안
보안 문제는 security@hashicorp.com으로 연락하거나 보안 정책을 따르세요.
지원
버그 신고와 기능 요청은 GitHub에 이슈를 여세요. 일반 질문과 토론은 GitHub Discussion을 여세요.