Terraform MCP Server

Terraform MCP Server

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

Возможности

• Поддержка двух транспортных протоколов: транспорт Stdio и StreamableHTTP с настраиваемыми конечными точками
• Интеграция с реестром Terraform: прямая интеграция с публичными API реестра Terraform для провайдеров, модулей и политик
• Поддержка 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 в файл пользовательских настроек (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.1.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.1.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) или через Настройки → Настройки Cursor → 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.1.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.1.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

Использование с расширениями 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.1.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

{
  "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. Вы можете использовать его в своем AI-ассистенте следующим образом:

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

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

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

Корпоративный прокси / Инспекция TLS (Zscaler и т.п.)

Если вы находитесь за корпоративным прокси, который выполняет инспекцию TLS (например, Zscaler Internet Access), вы можете увидеть ошибки сертификата:

tls: failed to verify certificate: x509: certificate signed by unknown authority

Решение: Смонтируйте корневой сертификат вашего ЦС в контейнер:

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.1.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.1.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 Discussion.