Terraform MCP Server

Terraform MCP Server

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

Содержание

Возможности

• Поддержка двух транспортов: транспорты 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-клиента. Пользователи должны тщательно проверять все выходные данные/рекомендации, чтобы убедиться в их соответствии лучшим практикам безопасности, целям экономической эффективности и требованиям соответствия своей организации перед внедрением.

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

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

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

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

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

Установка

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

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

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

{
  "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": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "hashicorp/terraform-mcp-server:0.2.3"
        ]
      }
    }
  }
}

При желании вы можете добавить аналогичный пример (т. е. без ключа mcp) в файл с именем .vscode/mcp.json в вашем рабочем пространстве. Это позволит вам поделиться конфигурацией с другими.

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

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

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

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

{
  "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.

{
  "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": {
      "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.

{
  "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"
      ],
      "disabled": false
    }
  }
}

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

Kubernetes (Helm)

Helm-чарт для развёртывания сервера в Kubernetes доступен по адресу 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

{
  "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_provider_docs,get_provider_details

Примечание: При работе в Docker следует задать TRANSPORT_HOST=0.0.0.0, чтобы разрешить подключения извне контейнера.

4. (Необязательно) Проверьте подключение в режиме http

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

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

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

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

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

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

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

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

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

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_provider_docs,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 как список разрешённых имён организаций HCP Terraform через запятую

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

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

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

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

export MCP_SESSION_MODE=stateless

Сквозная передача токенов для централизованных развёртываний

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

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

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

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

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

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

X-Forwarded-For и X-Real-IP задаются клиентами и промежуточными прокси, поэтому их можно подделать, если доверенный прокси перед сервером не перезаписывает их. По этой причине по умолчанию используется RemoteAddr, который доверяет только узлу, к которому сервер подключён напрямую. Включайте X-Real-IP или X-Forwarded-For только когда сервер находится за прокси, который вы контролируете и который задаёт эти заголовки. Некоторые балансировщики нагрузки, включая AWS Application Load Balancers, не задают X-Real-IP, поэтому в этом случае заголовок приходит напрямую от клиента и не должен использоваться.

Доверенные переходы

При использовании X-Forwarded-For задайте MCP_XFF_TRUSTED_HOPS равным числу прокси, которые вы используете перед сервером. Каждый прокси добавляет адрес, с которого он получил запрос, а не свой собственный адрес, поэтому IP-адрес клиента — это запись на столько позиций справа. Всё, что левее неё, было отправлено клиентом и может быть подделано.

Например, за одним балансировщиком нагрузки, таким как AWS ALB, задайте MCP_XFF_TRUSTED_HOPS=1. Заголовок 198.51.100.7 разрешается в 198.51.100.7, а заголовок 1.2.3.4, 198.51.100.7, где клиент сам отправил 1.2.3.4, также разрешается в 198.51.100.7. При MCP_XFF_TRUSTED_HOPS=2 и 1.2.3.4, 198.51.100.7, 10.0.0.5 сервер выбирает 198.51.100.7. Если число переходов больше числа записей или выбранная запись не является допустимым IP, сервер возвращается к RemoteAddr.

Слишком большое число переходов приведёт к доверию значению, предоставленному клиентом; слишком маленькое — к выбору адреса из вашей собственной инфраструктуры. Задайте точное число прокси, которые вы используете.

Ограничения

• Если запрос содержит несколько заголовков X-Forwarded-For, сервер объединяет их по порядку перед выбором записи. 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 (или значения по умолчанию). Запросы, пытающиеся задать TFE_ADDRESS через HTTP-заголовок или параметр запроса, отклоняются с кодом 403. Это предотвращает перенаправление клиентом запросов и токена Authorization на вредоносный сервер.
• Идентификация размещённого развёртывания: установка TF_MCP_SHARED_SECRET отправляет это значение в качестве заголовка X-Tf-Mcp-Secret при каждом запросе к HCP Terraform / TFE, позволяя бэкенду идентифицировать запросы от известного размещённого развёртывания (например, для применения списков разрешённых 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.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

Для конфигураций 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.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

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

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

Лицензия

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

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

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

Поддержка

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

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