Terraform MCP Server

공식

HashiCorp Terraform MCP 서버로, Terraform 레지스트리를 통한 프로바이더 및 모듈 검색을 포함한 Infrastructure as Code 워크플로우를 지원합니다.

Terraform MCP(으)로 무엇을 할 수 있나요?

  • Search Terraform Registry — 요청하여 search_providersget_provider_details를 사용해 공개 레지스트리에서 프로바이더나 모듈을 찾습니다.
  • Manage HCP Terraform workspaces — 워크스페이스 작업을 통해 워크스페이스를 생성, 업데이트 또는 삭제하고 변수, 태그, 실행을 처리합니다.
  • List organizations and projects — HCP Terraform 또는 Terraform Enterprise에서 조직 및 프로젝트 목록을 검색합니다.
  • Access private registry contentregistry-private 도구 세트를 사용하여 비공개 레지스트리의 프로바이더, 모듈 및 정책을 조회합니다.
  • Filter available tools--toolsets 또는 list_workspaces 같은 --tools 플래그를 사용하여 필요한 기능만 활성화합니다.

문서

Terraform MCP Server

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

목차

시작하기클라이언트 통합빌드 및 실행
기능
사전 요구 사항
명령줄 옵션
지침
설치
Visual Studio Code
Cursor
Claude Desktop, Amazon Q Developer 및 Kiro CLI
Claude Code
Codex CLI
Gemini 확장 프로그램
Bob IDE 및 Shell
소스에서 설치
Docker 이미지 로컬 빌드
전송 지원
Stdio 전송
StreamableHTTP 전송
서버 기능배포 및 보안도움말 및 기여
사용 가능한 도구
사용 가능한 리소스
사용 가능한 메트릭
도구 필터링
세션 모드
중앙 집중식 배포를 위한 토큰 전달
클라이언트 IP 전달
신뢰 모델
신뢰할 수 있는 홉
제한 사항
이전 버전에서 마이그레이션
지원되는 헤더
보안 고려 사항
중앙 집중식 배포 예시
문제 해결
기업 프록시 및 TLS 검사
개발
기여
라이선스
보안
지원

기능

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

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

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

주의: 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_SHARED_SECRETHCP Terraform / TFE에 대한 요청 시 X-Tf-Mcp-Secret 헤더로 전송되는 공유 비밀번호로, 호스팅된 MCP 배포에서 시작된 요청을 식별하는 데 사용됩니다. TLS를 통해서만 사용해야 합니다."" (비어 있음)
TFE_SKIP_TLS_VERIFYHCP Terraform 또는 Terraform Enterprise TLS 검증 건너뛰기false
LOG_LEVEL로깅 수준: trace, debug, info, warn, error, fatal, panic (--log-level 플래그를 재정의함)info
LOG_FORMAT로깅 형식: text 또는 json (--log-format 플래그를 재정의함)text
TRANSPORT_MODEHTTP 전송을 활성화하려면 streamable-http로 설정 (레거시 http 값도 지원됨)stdio
TRANSPORT_HOSTHTTP 서버를 바인딩할 호스트127.0.0.1
TRANSPORT_PORTHTTP 서버 포트8080
MCP_ENDPOINTHTTP 서버 엔드포인트 경로/mcp
MCP_REDIRECT_ROOT_URL/로의 요청을 리디렉션할 URL""
MCP_KEEP_ALIVESSE 연결에 대한 Keep-alive 간격(예: 30s, 1m). 비활성화하려면 00
MCP_SESSION_MODE세션 모드: stateful 또는 statelessstateful
MCP_ALLOWED_ORIGINSCORS에 허용된 출처의 쉼표로 구분된 목록"" (비어 있음)
MCP_CORS_MODECORS 모드: strict, development 또는 disabledstrict
MCP_TLS_CERT_FILETLS 인증서 파일 경로, localhost가 아닌 배포에 필요(예: /path/to/cert.pem)"" (비어 있음)
MCP_TLS_KEY_FILETLS 키 파일 경로, localhost가 아닌 배포에 필요(예: /path/to/key.pem)"" (비어 있음)
MCP_RATE_LIMIT_GLOBAL전역 속도 제한(형식: rps:burst)10:20
MCP_RATE_LIMIT_SESSION세션별 속도 제한(형식: rps:burst)5:10
MCP_ORGANIZATION_ALLOWLISTHTTP 서버에 액세스할 수 있는 HCP Terraform 조직 이름의 CSV 목록"" (비어 있음)
MCP_FORWARD_CLIENT_IPX-Forwarded-For를 통해 클라이언트 IP를 HCP Terraform / TFE로 전달. 활성화하려면 true로 설정false
MCP_REMOTE_IP_METHOD전달이 활성화된 경우 클라이언트 IP 소스 방법: RemoteAddr (직접 연결만), X-Real-IP 또는 X-Forwarded-ForRemoteAddr
MCP_XFF_TRUSTED_HOPSX-Forwarded-For 체인의 오른쪽에서 계산된 신뢰할 수 있는 프록시 홉 수. MCP_REMOTE_IP_METHOD=X-Forwarded-For일 때만 사용됨0
ENABLE_TF_OPERATIONS명시적 승인이 필요한 도구 활성화false
OTEL_METRICS_ENABLEDotel을 사용한 도구 및 서버 메트릭 활성화false
OTEL_METRICS_SERVICE_VERSION메트릭을 전송하는 terraform-mcp-server의 버전으로, 메트릭 속성을 설정하는 데 사용됩니다. 또한 여러 배포에서 메트릭을 추적하는 데 도움이 됩니다latest
OTEL_METRICS_SERVICE_NAME메트릭의 출처 식별(예: "terraform-mcp-server")terraform-mcp-server
OTEL_METRICS_EXPORT_INTERVAL메트릭 플러시 빈도 제어2
OTEL_METRICS_ENDPOINTOTel Collector 또는 백엔드의 URLlocalhost:4318
INSTANA_ENABLEDstreamable-http 서버에 대한 Instana 계측(메트릭 및 HTTP 요청 추적) 활성화. 서버에서 연결할 수 있는 Instana 에이전트가 필요합니다.false
INSTANA_SERVICE_NAMEInstana 계측이 활성화된 경우 MCP 서버에 사용할 서비스 이름terraform-mcp-server
# 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 서버 도구 사용에 대해 자세히 알아보십시오.

버전 0.3.0 이상버전 0.2.3 이하
{
  "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"
        ]
      }
    }
  }
}

선택적으로, mcp 키 없이 유사한 예제를 작업 공간의 .vscode/mcp.json라는 파일에 추가할 수 있습니다. 이렇게 하면 구성을 다른 사람과 공유할 수 있습니다.

버전 0.3.0 이상버전 0.2.3 이하
{
  "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"
      ]
    }
  }
}

Install in VS Code (docker) Install in VS Code Insiders (docker)

Cursor에서 사용

Cursor 구성(~/.cursor/mcp.json) 또는 설정 → Cursor 설정 → MCP에 다음을 추가하십시오:

버전 0.3.0 이상버전 0.2.3 이하
{
  "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"
      ]
    }
  }
}
Add terraform MCP server to Cursor

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

Claude Desktop에서 MCP 서버 도구를 사용하는 방법에 대한 자세한 내용은 사용자 문서를 참조하세요. Amazon Q DeveloperKiro CLI에서 MCP 서버 사용에 대해 자세히 알아보세요.

버전 0.3.0 이상버전 0.2.3 이하
{
  "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"
      ]
    }
  }
}

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

Codex CLI에서 사용하기

Codex CLI에서 MCP 서버 도구를 사용하고 추가하는 방법에 대한 자세한 내용은 사용자 문서를 참조하세요.

참고: 인증된 HCP Terraform 또는 Terraform Enterprise 도구를 사용하려면 Docker 명령에 TFE_ADDRESSTFE_TOKEN을 추가하세요.

  • 로컬(stdio) 전송
codex mcp add terraform -- docker run -i --rm hashicorp/terraform-mcp-server
  • 원격(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

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 사용하기를 참조하세요.

버전 0.3.0 이상버전 0.2.3 이하
{
  "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
    }
  }
}

소스에서 설치

최신 릴리스 버전 사용:

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
버전 0.3.0 이상버전 0.2.3 이하
{
  "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
  1. Docker 이미지를 빌드합니다:
make docker-build
  1. 이렇게 하면 다음 구성에서 사용할 수 있는 로컬 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을 설정해야 합니다.

  1. (선택 사항) http 모드에서 연결 테스트
# Test the connection
curl http://localhost:8080/health
  1. AI 어시스턴트에서 다음과 같이 사용할 수 있습니다:
{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "terraform-mcp-server:dev"
      ]
    }
  }
}

사용 가능한 도구

사용 가능한 도구는 여기에서 확인하세요 :link:

사용 가능한 리소스

사용 가능한 리소스는 여기에서 확인하세요 :link:

사용 가능한 메트릭

두 종류의 메트릭이 수집됩니다. 첫째, HTTP mux를 otelhttp.NewHandler(...)로 래핑하여 표준 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 Server는 여러 전송 프로토콜을 지원합니다:

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 설정
  • 조직 허용 목록: 허용된 HCP Terraform 조직 이름의 CSV 목록으로 MCP_ORGANIZATION_ALLOWLIST 또는 --organization-allowlist 설정

세션 모드

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

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

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

export MCP_SESSION_MODE=stateless

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

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

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를 소싱합니다:

메서드동작
RemoteAddr(기본값)직접 TCP 연결의 주소만 사용합니다. X-Forwarded-ForX-Real-IP을 무시합니다.
X-Real-IPX-Real-IP 헤더가 유효한 IP인 경우 사용하고, 그렇지 않으면 RemoteAddr으로 대체합니다.
X-Forwarded-ForX-Forwarded-For 체인을 사용하여 오른쪽에서 MCP_XFF_TRUSTED_HOPS 위치의 항목을 선택합니다. 값이 없거나 유효하지 않으면 RemoteAddr으로 대체합니다.

신뢰 모델

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

신뢰할 수 있는 홉

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

예를 들어, MCP_XFF_TRUSTED_HOPS=1200.1.2.3, 10.1.1.10 헤더가 있는 경우 서버는 200.1.2.3을 선택합니다. MCP_XFF_TRUSTED_HOPS=2108.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-ForMCP_XFF_TRUSTED_HOPS을 운영하는 프록시 수로 설정하세요.

지원되는 헤더

헤더설명
TFE_TOKENTerraform API 토큰
Authorization: Bearer <token>표준 Bearer 인증을 사용하는 대체 방법
TFE_SKIP_TLS_VERIFY요청에 대한 TLS 검증 건너뛰기

예시: 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 토큰을 악성 서버로 리디렉션할 수 없습니다.
  • 호스팅 배포 식별: TF_MCP_SHARED_SECRET을 설정하면 모든 HCP Terraform / TFE 요청에 해당 값이 X-Tf-Mcp-Secret 헤더로 전송되어 백엔드가 알려진 호스팅 배포의 요청을 식별할 수 있습니다(예: IP 허용 목록 적용). 헤더로 전송되는 정적 비밀번호이므로 TLS를 통해서만 사용하고 값을 자격 증명으로 취급하세요.
  • 쿼리 매개변수에 토큰을 절대 전달하지 마세요 - 서버는 이러한 요청을 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.3.0

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

문제 해결

기업 프록시 / TLS 검사(Zscaler 등)

Zscaler Internet Access와 같은 TLS 검사를 수행하는 기업 프록시 뒤에 있는 경우 인증서 오류가 발생할 수 있습니다:

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

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

환경에서 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엔드투엔드 테스트 실행
make docker-buildDocker 이미지 빌드
make run-httpHTTP 서버를 로컬에서 실행
make docker-run-httpHTTP 서버를 Docker에서 실행
make test-httpHTTP 헬스 엔드포인트 테스트
make clean빌드 산출물 제거
make help사용 가능한 모든 명령어 표시

기여

  1. 저장소를 포크합니다
  2. 기능 브랜치를 생성합니다
  3. 변경 사항을 적용합니다
  4. 테스트를 실행합니다
  5. 풀 리퀘스트를 제출합니다

라이선스

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

보안

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

지원

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

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