Terraform MCP Server

Terraform MCP Server — это сервер Model Context Protocol (MCP), который бесшовно интегрируется с API Terraform Registry и HCP Terraform, открывая расширенные возможности автоматизации и взаимодействия для разработки Infrastructure as Code (IaC).

Содержание

Начало работы	Интеграции с клиентами	Сборка и запуск
Возможности Предварительные требования Параметры командной строки Инструкции	Установка 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: прямое взаимодействие с публичными API Terraform Registry для провайдеров, модулей и политик
Поддержка HCP Terraform и Terraform Enterprise: полноценное управление рабочими пространствами, вывод списка организаций и проектов, доступ к приватному реестру
Операции с рабочими пространствами: создание, обновление и удаление рабочих пространств с поддержкой переменных, тегов и управления запусками
Метрики OTel для мониторинга использования инструментов: интеграция с метриками OpenTelemetry для отслеживания объёма вызовов инструментов, задержек и сбоев в режиме Streamable HTTP. Также предоставляет стандартные метрики HTTP-сервера при включении этой функции

Замечание по безопасности: в зависимости от запроса MCP-сервер может раскрывать определённые данные Terraform MCP-клиенту и LLM. Не используйте MCP-сервер с недоверенными MCP-клиентами или LLM.

Правовое замечание: использование стороннего MCP-клиента/LLM регулируется исключительно условиями использования такого MCP/LLM, и IBM не несёт ответственности за работу этих сторонних инструментов. IBM прямо отказывается от любых гарантий и ответственности в отношении сторонних MCP-клиентов/LLM и может быть не в состоянии оказать поддержку в решении проблем, вызванных сторонними инструментами.

Внимание: выходные данные и рекомендации, предоставляемые MCP-сервером, формируются динамически и могут различаться в зависимости от запроса, модели и подключённого MCP-клиента. Пользователям следует тщательно проверять все выходные данные и рекомендации на соответствие лучшим практикам безопасности своей организации, целям экономической эффективности и требованиям соответствия перед внедрением.

Предварительные требования

Убедитесь, что Docker установлен и запущен, чтобы использовать сервер в контейнеризованной среде.
Установите AI-ассистента, поддерживающего Model Context Protocol (MCP).

Параметры командной строки

Переменные окружения:

Переменная	Описание	Значение по умолчанию
`TFE_ADDRESS`	Задаёт адрес Terraform Enterprise/HCP Terraform для вызовов API. Должен включать протокол (например, `https://app.terraform.io`). В режиме streamable-http это единственный способ задать адрес; клиенты не могут передать его через заголовок или параметр запроса.	Опционально
`TFE_TOKEN`	API-токен Terraform Enterprise	`""` (пусто)
`TF_MCP_SHARED_SECRET`	Общий секрет, отправляемый в заголовке `X-Tf-Mcp-Secret` при запросах к HCP Terraform / TFE; используется для идентификации запросов, исходящих от размещённого развёртывания MCP. Следует использовать только поверх TLS.	`""` (пусто)
`TFE_SKIP_TLS_VERIFY`	Пропустить проверку TLS для HCP Terraform или Terraform Enterprise	`false`
`LOG_LEVEL`	Уровень логирования: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic` (переопределяет флаг `--log-level`)	`info`
`LOG_FORMAT`	Формат логирования: `text` или `json` (переопределяет флаг `--log-format`)	`text`
`TRANSPORT_MODE`	Установите `streamable-http`, чтобы включить HTTP-транспорт (устаревшее значение `http` по-прежнему поддерживается)	`stdio`
`TRANSPORT_HOST`	Хост для привязки HTTP-сервера	`127.0.0.1`
`TRANSPORT_PORT`	Порт HTTP-сервера	`8080`
`MCP_ENDPOINT`	Путь эндпоинта HTTP-сервера	`/mcp`
`MCP_REDIRECT_ROOT_URL`	URL для перенаправления запросов к `/`	`""`
`MCP_KEEP_ALIVE`	Интервал keep-alive для SSE-соединений (например, 30s, 1m). 0 — отключено	`0`
`MCP_SESSION_MODE`	Режим сессии: `stateful` или `stateless`	`stateful`
`MCP_ALLOWED_ORIGINS`	Список разрешённых источников для CORS через запятую	`""` (пусто)
`MCP_CORS_MODE`	Режим CORS: `strict`, `development` или `disabled`	`strict`
`MCP_TLS_CERT_FILE`	Путь к файлу TLS-сертификата; обязателен для развёртывания не на localhost (например, `/path/to/cert.pem`)	`""` (пусто)
`MCP_TLS_KEY_FILE`	Путь к файлу TLS-ключа; обязателен для развёртывания не на localhost (например, `/path/to/key.pem`)	`""` (пусто)
`MCP_RATE_LIMIT_GLOBAL`	Глобальное ограничение скорости (формат: `rps:burst`)	`10:20`
`MCP_RATE_LIMIT_SESSION`	Ограничение скорости на сессию (формат: `rps:burst`)	`5:10`
`MCP_ORGANIZATION_ALLOWLIST`	CSV-список названий организаций HCP Terraform, которым разрешён доступ к HTTP-серверу	`""` (пусто)
`MCP_FORWARD_CLIENT_IP`	Передавать IP-адрес клиента в HCP Terraform / TFE через `X-Forwarded-For`. Установите `true` для включения	`false`
`MCP_REMOTE_IP_METHOD`	Способ определения IP-адреса клиента при включённой передаче: `RemoteAddr` (только прямое соединение), `X-Real-IP` или `X-Forwarded-For`	`RemoteAddr`
`MCP_XFF_TRUSTED_HOPS`	Количество доверенных промежуточных узлов прокси, отсчитываемых справа в цепочке `X-Forwarded-For`. Используется только при `MCP_REMOTE_IP_METHOD=X-Forwarded-For`	`0`
`ENABLE_TF_OPERATIONS`	Включить инструменты, требующие явного одобрения	`false`
`OTEL_METRICS_ENABLED`	Включить метрики инструментов и сервера с использованием otel	`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_ENDPOINT`	URL вашего OTel Collector или бэкенда	`localhost:4318`
`INSTANA_ENABLED`	Включить инструментацию Instana (метрики и трассировку HTTP-запросов) для сервера streamable-http. Требуется агент Instana, доступный серверу.	`false`
`INSTANA_SERVICE_NAME`	Если инструментация Instana включена — имя сервиса, используемое для MCP-сервера	`terraform-mcp-server`

] [--tools ]

Режим StreamableHTTP

terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--organization-allowlist ] [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets ] [--tools ]">

# Режим Stdio
terraform-mcp-server stdio [--log-file /path/to/log] [--log-level info] [--log-format text] [--toolsets <toolsets>] [--tools <tools>]

# Режим StreamableHTTP
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; чтобы воспользоваться им, закоммитьте файл с именем AGENTS.md в каталог, где хранятся ваши конфигурации Terraform.

Установка

Использование с Visual Studio Code

Добавьте следующий блок JSON в файл пользовательских настроек (JSON) в VS Code. Для этого нажмите Ctrl + Shift + P и введите Preferences: Open User Settings (JSON).

Подробнее об использовании инструментов MCP-сервера — в документации режима агента VS Code.

Версия 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"
      ]
    }
  }
}

Использование с Cursor

Добавьте эту конфигурацию в файл настроек Cursor (~/.cursor/mcp.json) или через Settings → Cursor Settings → 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"
      ]
    }
  }
}

Использование с Claude Desktop / Amazon Q Developer / Kiro CLI

Подробнее об использовании инструментов MCP-сервера в Claude Desktop — в пользовательской документации. Дополнительные сведения об использовании MCP-сервера — в документации Amazon Q Developer и Kiro CLI.

Версия 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

Подробнее об использовании и добавлении инструментов MCP-сервера в Claude Code — в пользовательской документации.

Локальный транспорт (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

Подробнее об использовании и добавлении инструментов MCP-сервера в Codex CLI — в пользовательской документации.

Примечание: добавьте TFE_ADDRESS и TFE_TOKEN в команды Docker, чтобы использовать инструменты HCP Terraform или Terraform Enterprise с аутентификацией.

Локальный транспорт (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

В целях безопасности не храните учётные данные прямо в коде. Создайте или обновите файл ~/.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

Подробнее об использовании и добавлении инструментов MCP-серверов в Bob IDE или Shell — в разделе Использование MCP в Bob.

Версия 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
    }
  }
}

Kubernetes (Helm)

Для развёртывания сервера в Kubernetes доступен Helm-чарт в каталоге helm/terraform-mcp-server.

Установка из исходного кода

Чтобы установить последнюю релизную версию:

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

Чтобы установить версию из ветки main:

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-образ:

Клонируйте репозиторий:

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

Соберите Docker-образ:

make docker-build

Будет создан локальный 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, чтобы разрешить подключения извне контейнера.

(Опционально) Проверьте подключение в режиме http

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

Вы можете использовать его в своём AI-ассистенте следующим образом:

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

Доступные инструменты

Ознакомьтесь с доступными инструментами здесь 🔗

Доступные ресурсы

Ознакомьтесь с доступными ресурсами здесь 🔗

Доступные метрики

Собираются метрики двух типов.

Во-первых, стандартные метрики HTTP-сервера добавляются путём оборачивания HTTP mux в otelhttp.NewHandler(...). При этом публикуются:

http.server.request.body.size
http.server.response.body.size
http.server.request.duration

Во-вторых, MCP-сервер записывает пользовательские метрики инструментов во время их выполнения с помощью хуков MCP (BeforeCallTool / AfterCallTool). При этом публикуются:

mcp_tool_calls_total
mcp_tool_errors_total
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, поддерживающий как прямые HTTP-запросы, так и потоки Server-Sent Events (SSE). Рекомендуется для удалённых/распределённых конфигураций.

Возможности:

Конечная точка: http://{hostname}:8080/mcp
Проверка работоспособности: http://{hostname}:8080/health
Конфигурация через переменные окружения: задайте TRANSPORT_MODE=http или TRANSPORT_PORT=8080, чтобы включить
Список разрешённых организаций: задайте MCP_ORGANIZATION_ALLOWLIST или --organization-allowlist как CSV-список разрешённых названий организаций HCP Terraform

Режимы сессий

Terraform MCP Server поддерживает два режима сессий при использовании транспорта StreamableHTTP:

Режим с сохранением состояния (по умолчанию): сохраняет состояние сессии между запросами, обеспечивая операции с учётом контекста.
Режим без сохранения состояния: каждый запрос обрабатывается независимо, без сохранения состояния сессии; это может быть полезно для отказоустойчивых развёртываний или при использовании балансировщиков нагрузки.

Чтобы включить режим без сохранения состояния, задайте переменную окружения:

export MCP_SESSION_MODE=stateless

Проброс токенов для централизованных развёртываний

При централизованном запуске MCP-сервера (в режиме StreamableHTTP) для нескольких пользователей каждый пользователь может передавать собственный токен Terraform через HTTP-заголовки для применения RBAC. Это позволяет одному экземпляру сервера обслуживать нескольких пользователей с разными правами.

Если настроен MCP_ORGANIZATION_ALLOWLIST или --organization-allowlist, список разрешённых организаций должен быть CSV-списком названий организаций HCP Terraform. Сервер требует Authorization: Bearer и отклоняет запросы, если этот токен не может получить доступ хотя бы к одной организации из CSV-списка. Bearer-токен имеет приоритет, если запрос также содержит заголовок TFE_TOKEN; это гарантирует, что для запросов к Terraform API используется токен, проверенный по списку разрешённых организаций. Сопоставление названий организаций нечувствительно к регистру. Если настроенное значение CSV содержит ноль названий организаций, сервер завершает работу с ошибкой malformed organization allowlist.

Проброс IP-адреса клиента

При централизованном запуске MCP-сервера за прокси или балансировщиком нагрузки можно пробрасывать исходный IP-адрес клиента в HCP Terraform / TFE через заголовок X-Forwarded-For. По умолчанию эта функция отключена; её необходимо включить с помощью MCP_FORWARD_CLIENT_IP=true.

Когда функция включена, сервер определяет IP-адрес клиента в соответствии с MCP_REMOTE_IP_METHOD:

Метод	Поведение
`RemoteAddr` (по умолчанию)	Использует только адрес прямого TCP-соединения. Игнорирует `X-Forwarded-For` и `X-Real-IP`.
`X-Real-IP`	Использует заголовок `X-Real-IP`, если он содержит допустимый IP-адрес; в противном случае возвращается к `RemoteAddr`.
`X-Forwarded-For`	Использует цепочку `X-Forwarded-For`, выбирая запись на `MCP_XFF_TRUSTED_HOPS` позиций справа. Возвращается к `RemoteAddr`, если значение отсутствует или недопустимо.

Модель доверия

Заголовки 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 равным количеству прокси, которые вы используете.

Поддерживаемые заголовки

Заголовок	Описание
`TFE_TOKEN`	Токен Terraform API
`Authorization: Bearer`	Альтернативный метод с использованием стандартной 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 на стороне сервера (или из значения по умолчанию). Запросы, которые пытаются задать TFE_ADDRESS через HTTP-заголовок или query-параметр, отклоняются с кодом 403. Это исключает возможность перенаправления клиентом запросов и токена Authorization на вредоносный сервер.
Идентификация hosted-развёртывания: при установке TF_MCP_SHARED_SECRET это значение передаётся в заголовке X-Tf-Mcp-Secret с каждым запросом к HCP Terraform / TFE, что позволяет бэкенду распознавать запросы от известного hosted-развёртывания (например, для применения списков разрешённых IP-адресов). Это статический секрет, передаваемый в заголовке, поэтому используйте его только поверх TLS и обращайтесь с этим значением как с учётными данными.
Никогда не передавайте токены в query-параметрах — сервер отклонит такие запросы с ошибкой 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 и т. п.)

Если вы работаете через корпоративный прокси, выполняющий 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.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`	Запуск end-to-end тестов
`make docker-build`	Сборка Docker-образа
`make run-http`	Локальный запуск HTTP-сервера
`make docker-run-http`	Запуск HTTP-сервера в Docker
`make test-http`	Проверка HTTP-эндпоинта состояния
`make clean`	Удаление артефактов сборки
`make help`	Показ всех доступных команд

Участие в разработке

Сделайте форк репозитория
Создайте ветку для новой функциональности
Внесите изменения
Запустите тесты
Отправьте pull request

Лицензия

Этот проект распространяется на условиях открытой лицензии MPL-2.0. Полный текст условий смотрите в файле LICENSE.

Безопасность

По вопросам безопасности обращайтесь по адресу security@hashicorp.com или ознакомьтесь с нашей политикой безопасности.

Поддержка

Для сообщений об ошибках и предложений по новым функциям создайте issue на GitHub.

Для общих вопросов и обсуждений откройте GitHub Discussion.