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 для мониторинга использования инструментов: Интеграция с измерителями open telemetry для отслеживания объема вызовов инструментов, задержек и сбоев в режиме 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.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 в вашей рабочей области. Это позволит вам поделиться конфигурацией с другими.

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

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

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

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

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

{
  "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_providers,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_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 <token> и отклоняет запросы, если этот токен не может получить доступ хотя бы к одной организации в CSV-списке. Bearer-токен имеет приоритет, если запрос также включает заголовок TFE_TOKEN, что гарантирует, что токен, проверенный списком разрешённых, является токеном, используемым для запросов к API Terraform. Сопоставление имён организаций нечувствительно к регистру. Если настроенное 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 только тогда, когда сервер находится за прокси, которым вы управляете и который устанавливает эти заголовки.

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

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

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

Пример: 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.3.0

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

Устранение неполадок

Корпоративный прокси / проверка 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

Участие

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

Лицензия

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

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

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

Поддержка

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

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