Terraform Cloud MCP Server

Terraform Cloud MCP Server

AI アシスタントを Terraform Cloud API と統合し、自然な会話を通じてインフラストラクチャを管理できる Model Context Protocol（MCP）サーバーです。Pydantic モデルを使用し、ドメイン固有のモジュールを中心に構成されています。Claude、Claude Code CLI、Claude Desktop、Cursor、Copilot Studio など、MCP をサポートするあらゆるプラットフォームと互換性があります。

---

機能

• アカウント管理：認証済みユーザーまたはサービスアカウントのアカウント詳細を取得します。
• ワークスペース管理：ワークスペースの作成、読み取り、更新、ロック／ロック解除、および（安全機能を備えた）任意の削除ができます。
• プロジェクト管理：プロジェクトの作成、一覧表示、更新、および任意の削除ができます。プロジェクトタグの関連付けを管理し、ワークスペースをプロジェクト間で移動できます。
• 実行管理：実行の作成、一覧表示、詳細の取得、適用、破棄、キャンセルができます。
• プラン管理：高度な HTTP リダイレクト処理を備え、プランの詳細と JSON 実行出力を取得します。
• 適用管理：適用の詳細を取得し、失敗した状態アップロードから復旧します。
• 組織管理：組織の一覧表示、作成、更新、組織のエンタイトルメントの確認、および（安全機能を備えた）任意の削除ができます。
• コスト見積もり：インフラストラクチャの変更に関する詳細なコスト見積もりを取得します。提案される月額コスト、以前のコスト、リソース数、使用量の予測が含まれます。
• 評価結果：Terraform Cloud のヘルス評価から、ヘルス評価の詳細、JSON 出力、スキーマファイル、ログを取得します。
• 状態バージョン管理：状態バージョンの一覧表示、取得、作成、ダウンロードができ、ワークスペースの現在の状態を取得します。
• 状態バージョンの出力：値や機密情報に関する情報を含め、状態バージョンから特定の出力を一覧表示して取得します。
• 変数管理：ワークスペース変数と変数セットを包括的に管理します。作成、更新、割り当て、および（安全機能を備えた）任意の削除ができます。

パフォーマンス機能

• 監査に配慮した応答フィルタリング：監査への完全な準拠を維持しながら、保守的なトークン最適化（5～15%削減）を行います。包括的なコンプライアンス対応のため、すべてのユーザー説明責任、セキュリティ設定、変更追跡データを保持します。

安全機能

• 破壊的操作の制御：削除操作はデフォルトで無効になっており、環境変数による明示的な有効化が必要です。
• 読み取り専用モード：本番環境で最大限の安全性を確保するため、READ_ONLY_TOOLS=true によってすべての書き込み操作を無効にできます。
• 破壊的操作の警告：危険を伴う可能性のあるツールについて、MCP クライアントに適切な破壊的操作の警告を通知します。
• 環境ベースの安全設定：本番環境と開発環境で異なる安全設定を適用できます。

---

クイックスタート

前提条件

• Python 3.12+
• MCP（FastMCP と開発ツールを含む）
• uv パッケージマネージャー（推奨）または pip
• Terraform Cloud API トークン

Terraform Cloud API トークンの作成

この MCP サーバーを使用するには、Terraform Cloud（または Terraform Enterprise）の API トークンが必要です。

1. HCP Terraform（またはお使いの Terraform Enterprise インスタンス）にサインインします
2. 右上のアバターをクリックし、User Settings を選択します
3. 左側のサイドバーで Tokens に移動します
4. Create an API token をクリックします
5. 説明を入力します（例：「MCP Server」）
6. 有効期限を設定します（セキュリティのため推奨）
7. Generate token をクリックします
8. トークンをすぐにコピーします。表示されるのは一度だけです

以下の設定手順で、このトークンを TFC_TOKEN 環境変数として使用します。

API トークンの種類と権限の詳細については、HCP Terraform API Tokens documentation を参照してください。

環境変数

• TFC_TOKEN - Terraform Cloud API トークン（必須）
• TFC_ADDRESS - Terraform Cloud／Enterprise のアドレス（任意、デフォルトは https://app.terraform.io）
• ENABLE_DELETE_TOOLS - 破壊的操作の有効／無効を切り替えます（任意、デフォルトは false）
• READ_ONLY_TOOLS - 読み取り専用操作のみを有効にします（任意、デフォルトは false）
• ENABLE_RAW_RESPONSE - フィルター済みレスポンスではなく、生のレスポンスを返します（任意、デフォルトは false）

---

インストール

オプション 1：ローカルインストール

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install package
uv pip install .

オプション 2：Docker インストール

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Build the Docker image
docker build -t terraform-cloud-mcp:latest .

Claude 環境への追加

Claude Code CLI への追加

# Add to Claude Code with your Terraform Cloud token
claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=false -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To use a self-hosted Terraform Enterprise instance:
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e TFC_ADDRESS=https://terraform.example.com -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

# To enable delete operations (use with caution):
# claude mcp add -e TFC_TOKEN=YOUR_TF_TOKEN -e ENABLE_DELETE_TOOLS=true -s user terraform-cloud-mcp -- "terraform-cloud-mcp"

Claude Desktop への追加

claude_desktop_config.json 設定ファイルを作成します。

• mac：~/Library/Application Support/Claude/claude_desktop_config.json
• win：%APPDATA%\Claude\claude_desktop_config.json

ローカルインストールの設定：

{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "/path/to/uv", # Get this by running: `which uv`
      "args": [
        "--directory",
        "/path/to/your/terraform-cloud-mcp", # Full path to this project
        "run",
        "terraform-cloud-mcp"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here", # replace with actual token
        "TFC_ADDRESS": "https://app.terraform.io", # optional, change for self-hosted TFE
        "ENABLE_DELETE_TOOLS": "false", # set to "true" to enable destructive operations/tools
        "READ_ONLY_TOOLS": "false" # set to  "true" to only enable ready-only operations/tools
      }
    }
  }
}

Docker の設定：

{
  "mcpServers": {
    "terraform-cloud-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TFC_TOKEN",
        "-e", "TFC_ADDRESS",
        "-e", "ENABLE_DELETE_TOOLS",
        "-e", "READ_ONLY_TOOLS",
        "terraform-cloud-mcp:latest"
      ],
      "env": {
        "TFC_TOKEN": "your_actual_token_here",
        "TFC_ADDRESS": "https://app.terraform.io",
        "ENABLE_DELETE_TOOLS": "false",
        "READ_ONLY_TOOLS": "false"
      }
    }
  }
}

your_terraform_cloud_token を実際の Terraform Cloud API トークンに置き換えてください。

その他の MCP 対応プラットフォーム

その他のプラットフォーム（Cursor、Copilot Studio、Glama など）では、MCP サーバーの追加方法について各プラットフォーム固有の手順に従ってください。ほとんどのプラットフォームでは、次の項目が必要です。

1. サーバーのパス、またはサーバーを起動するコマンド。
2. Terraform Cloud API トークン用の環境変数（TFC_TOKEN）。
3. セルフホストの Terraform Enterprise 用の任意の環境変数（TFC_ADDRESS）。
4. 削除操作を有効にする任意の環境変数（破壊的操作の場合は ENABLE_DELETE_TOOLS=true）。
5. 読み取り専用モード用の任意の環境変数（すべての書き込み操作を無効にするには READ_ONLY_TOOLS=true）。
6. 必要に応じてサーバーを自動起動する設定。

---

利用可能なツール

注：READ_ONLY_TOOLS=true の場合、作成、更新、削除、適用、状態変更の操作はすべて無効になります。読み取り操作（一覧表示、取得、表示）のみ利用できます。

アカウントツール

• get_account_details(): 認証済みユーザーまたはサービスアカウントのアカウント情報を取得します。

ワークスペース管理ツール

一覧表示と検索

• list_workspaces(organization, page_number, page_size, search): ワークスペースを一覧表示し、絞り込みます。
• get_workspace_details(workspace_id, organization, workspace_name): 特定のワークスペースの詳細情報を取得します。

作成と更新

• create_workspace(organization, name, params): 任意のパラメーターを指定して新しいワークスペースを作成します。
• update_workspace(organization, workspace_name, params): 既存のワークスペース設定を更新します。

削除（ENABLE_DELETE_TOOLS=true が必要）

• delete_workspace(organization, workspace_name): ワークスペースとそのすべての内容を削除します。
• safe_delete_workspace(organization, workspace_name): ワークスペースがリソースを管理していない場合にのみ削除します。

注：削除操作は安全のため、デフォルトでは無効です。これらの破壊的操作を有効にするには、ENABLE_DELETE_TOOLS=true を設定してください。

ロックとロック解除

• lock_workspace(workspace_id, reason): ワークスペースをロックして、実行を防止します。
• unlock_workspace(workspace_id): ワークスペースのロックを解除して、実行を許可します。
• force_unlock_workspace(workspace_id): 別のユーザーによってロックされたワークスペースを強制的にロック解除します。

実行管理ツール

• create_run(workspace_id, params): ID を使用してワークスペースに Terraform の実行を作成し、キューに追加します。
• list_runs_in_workspace(workspace_id, ...): ID を使用して、特定のワークスペース内の実行を一覧表示し、絞り込みます。
• list_runs_in_organization(organization, ...): 組織全体の実行を一覧表示し、絞り込みます。
• get_run_details(run_id): 特定の実行の詳細情報を取得します。
• apply_run(run_id, comment): 確認待ちの実行を適用します。
• discard_run(run_id, comment): 確認待ちの実行を破棄します。
• cancel_run(run_id, comment): 計画中または適用中の実行をキャンセルします。
• force_cancel_run(run_id, comment): 実行を直ちに強制キャンセルします。
• force_execute_run(run_id): 先行する実行をキャンセルして、保留中の実行を強制的に実行します。

プラン管理ツール

• get_plan_details(plan_id): 特定のプランの詳細情報を取得します。
• get_plan_json_output(plan_id): 適切なリダイレクト処理を行い、特定のプランの JSON 実行プランを取得します。
• get_run_plan_json_output(run_id): 適切なリダイレクト処理を行い、実行から JSON 実行プランを取得します。
• get_plan_logs(plan_id): プラン操作のログを取得します。

適用管理ツール

• get_apply_details(apply_id): 特定の適用の詳細情報を取得します。
• get_errored_state(apply_id): 復旧のため、失敗した適用からエラー状態を取得します。
• get_apply_logs(apply_id): 適用操作のログを取得します。

プロジェクト管理ツール

• create_project(organization, name, params): オプションのパラメーターを指定して、新しいプロジェクトを作成します。
• update_project(project_id, params): 既存のプロジェクトの設定を更新します。
• list_projects(organization, ...): 組織内のプロジェクトを一覧表示し、絞り込みます。
• get_project_details(project_id): 特定のプロジェクトの詳細情報を取得します。
• delete_project(project_id): プロジェクトを削除します（ワークスペースが含まれている場合、削除は失敗します）。ENABLE_DELETE_TOOLS=true が必要です
• list_project_tag_bindings(project_id): プロジェクトに紐付けられたタグを一覧表示します。
• add_update_project_tag_bindings(project_id, tag_bindings): プロジェクトのタグの紐付けを追加または更新します。
• move_workspaces_to_project(project_id, workspace_ids): ワークスペースをプロジェクトに移動します。

組織管理ツール

• get_organization_details(organization): 特定の組織の詳細情報を取得します。
• get_organization_entitlements(organization): 組織の機能に関する権限セットを表示します。
• list_organizations(page_number, page_size, query, query_email, query_name): 組織を一覧表示し、絞り込みます。
• create_organization(name, email, params): オプションのパラメーターを指定して、新しい組織を作成します。
• update_organization(organization, params): 既存の組織の設定を更新します。
• delete_organization(organization): 組織とそのすべてのコンテンツを削除します。ENABLE_DELETE_TOOLS=true が必要です

コスト見積もりツール

• get_cost_estimate_details(cost_estimate_id): 特定のコスト見積もりの詳細情報を取得します。これには、リソース数（一致したものと一致しなかったもの）、変更前の月額コスト、提案された月額コスト、月額コストの差分見積もりが含まれます。特定の実行に対応するコスト見積もり ID を見つけるには、実行の関連情報を使用します。

アセスメント結果ツール

• get_assessment_result_details(assessment_result_id): 特定のヘルスアセスメント結果の詳細情報を取得します。
• get_assessment_json_output(assessment_result_id): アセスメント結果から JSON 実行プランを取得します。
• get_assessment_json_schema(assessment_result_id): アセスメント結果から JSON スキーマファイルを取得します。
• get_assessment_log_output(assessment_result_id): アセスメント結果の操作ログを取得します。

State Version Management Tools

• list_state_versions(organization, workspace_name, page_number, page_size, filter_status): ワークスペース内のステートバージョンを一覧表示し、フィルタリングします。
• get_current_state_version(workspace_id): ワークスペースの現在のステートバージョンを取得します。
• get_state_version(state_version_id): 指定したステートバージョンの詳細を取得します。
• create_state_version(workspace_id, serial, md5, params): ワークスペースに新しいステートバージョンを作成します。
• download_state_file(state_version_id, json_format): 生データまたは JSON 形式のステートファイルをダウンロードします。

State Version Outputs Tools

• list_state_version_outputs(state_version_id, page_number, page_size): 指定したステートバージョンの出力を一覧表示します。
• get_state_version_output(state_version_output_id): 指定したステートバージョン出力の詳細を取得します。

Variables Management Tools

Workspace Variables

• list_workspace_variables(workspace_id): ワークスペースのすべての変数（Terraform 変数および環境変数）を一覧表示します。
• create_workspace_variable(workspace_id, key, category, params): ワークスペースに新しい変数を作成します。
• update_workspace_variable(workspace_id, variable_id, params): 既存のワークスペース変数を更新します。
• delete_workspace_variable(workspace_id, variable_id): ワークスペース変数を削除します。ENABLE_DELETE_TOOLS=true が必要です

Variable Sets

• list_variable_sets(organization, page_number, page_size): 組織内の変数セットを一覧表示します。
• get_variable_set(varset_id): 指定した変数セットの詳細を取得します。
• create_variable_set(organization, name, params): 新しい変数セットを作成します。
• update_variable_set(varset_id, params): 既存の変数セットを更新します。
• delete_variable_set(varset_id): 変数セットとそのすべての変数を削除します。ENABLE_DELETE_TOOLS=true が必要です
• assign_variable_set_to_workspaces(varset_id, workspace_ids): 変数セットをワークスペースに割り当てます。
• unassign_variable_set_from_workspaces(varset_id, workspace_ids): ワークスペースから変数セットの割り当てを解除します。
• assign_variable_set_to_projects(varset_id, project_ids): 変数セットをプロジェクトに割り当てます。
• unassign_variable_set_from_projects(varset_id, project_ids): プロジェクトから変数セットの割り当てを解除します。

Variable Set Variables

• list_variables_in_variable_set(varset_id): 変数セット内のすべての変数を一覧表示します。
• create_variable_in_variable_set(varset_id, key, category, params): 変数セットに変数を作成します。
• update_variable_in_variable_set(varset_id, var_id, params): 変数セット内の変数を更新します。
• delete_variable_from_variable_set(varset_id, var_id): 変数セットから変数を削除します。ENABLE_DELETE_TOOLS=true が必要です

注：変数管理では、Terraform の入力変数と環境変数の両方を扱います。機密変数の値はセキュリティ保護のため非表示になります。削除操作はデフォルトで無効になっており、ENABLE_DELETE_TOOLS=true が必要です。

---

開発ガイド

コーディング規約、Pydantic のパターン、コントリビューションのワークフローなど、開発に関する詳しいガイダンスについては、開発ドキュメントを参照してください。

開発環境のクイックセットアップ

# Clone the repository
git clone https://github.com/severity1/terraform-cloud-mcp.git
cd terraform-cloud-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with development dependencies
uv pip install -e .
uv pip install black mypy pydantic ruff

基本的な開発コマンド

# Run the server in development mode
mcp dev terraform_cloud_mcp/server.py

# Run tests and quality checks
uv run -m mypy .
uv run -m ruff check .
uv run -m black .

コード構成、アーキテクチャ、開発ワークフロー、コード品質ガイドラインについて詳しくは、docs/DEVELOPMENT.mdを参照してください。

---

ドキュメント

コードベースには、包括的なドキュメントが含まれています。

• コードコメント：実装上の判断の「理由」を説明することに重点を置いています
• Docstring：すべての公開関数とクラスに、詳細な docstring が含まれています
• 実装リファレンス：開発ドキュメントでは、コードスニペットの代わりに実際のコード例を参照するようになりました
• サンプルファイル：docs/ ディレクトリには、各分野の詳細なサンプルが含まれています。
  • docs/FILTERING_SYSTEM.md：監査に安全な応答フィルタリングシステムの包括的なガイド（トークンを5～15%削減し、監査コンプライアンスを100%維持）
  • docs/DEVELOPMENT.md：実際のコードを参照した開発基準とコーディングガイドライン
  • docs/API_REFERENCES.md：実装状況を含むTerraform Cloud APIドキュメントへのリンク
  • docs/CONTRIBUTING.md：プロジェクトへの貢献に関するガイドライン
  • docs/models/：すべてのモデルタイプのリファレンスドキュメント
  • docs/tools/：各ツールの詳細なリファレンスドキュメント
  • docs/conversations/：APIを使った会話フローのサンプル

トラブルシューティング

1. サーバーログを確認します（デバッグログはデフォルトで有効です）
2. MCP Inspector（http://localhost:5173）を使ってデバッグします
3. server.py では、デバッグログがすでに有効になっています。

   import logging
   logging.basicConfig(level=logging.DEBUG)
   

---

貢献

皆さまからの貢献を歓迎します！このプロジェクトに貢献したい場合は、Issue またはプルリクエストを作成してください。

始め方、コード品質の基準、プルリクエストの手順について詳しくは、貢献ガイドをご覧ください。

免責事項

このプロジェクトは、HashiCorp または Terraform とは提携、関係、推奨のいずれもありません。 「Terraform」と「Terraform Cloud」はHashiCorpの商標です。 このプロジェクトは、フェアユースの範囲内でTerraform Cloudの公開APIを利用しているにすぎません。