Pulumi MCPサーバーの使い方 — ClaudeからIaCを操作する

@pulumi/mcp-serverは、クラウドインフラをコードで管理するPulumiを開発するPulumi Corporationが公開するnpmパッケージのMCPサーバーです。Pulumi CLIのプレビュー・デプロイ・状態同期をClaude Codeから直接呼び出せるほか、Pulumi Registryのリソース・関数情報も検索できます。ローカルのPulumiプロジェクトに対してstdio接続で動く軽量なサーバーで、Docker版イメージmcp/pulumiも提供されています。

なお「Pulumi MCPサーバー」という名前は、実はもう1つ存在します。Pulumi Cloudに接続してNeo(自律実行エージェント)にタスクを委任する、OAuth認証のホスト型サーバーです。両者は名前が同じでも別物で、混同すると設定でつまずきます。記事の後半で両者の違いを表にまとめます。

@pulumi/mcp-serverとは

@pulumi/mcp-serverとは、接続されたAIエージェントにInfrastructure as Code開発の実行能力を与えるMCPサーバーです。npmパッケージとして配布され、直近の公開バージョンは0.2.0(2025年9月26日公開)です。GitHub上のソースリポジトリは非公開化されていますが、npm・Docker Hub双方のパッケージ自体は配布が継続しています。

npm上の公開履歴を見ると、初版の0.1.0は2025年4月4日に公開され、そこから0.2.0まで14回のバージョンアップを重ねています。パッケージがdeprecated扱いになっている形跡はなく配布自体は継続していますが、0.2.0(2025年9月26日)以降は新バージョンが公開されていません。積極的に機能追加が続いているツールではないと理解したうえで使うのが実態に合っています。Docker Hub側のmcp/pulumiイメージの最終更新は2025年9月23日で、npm版0.2.0の公開(2025年9月26日)より3日早い日付です。Docker版のイメージがビルドされた時点ではnpm版0.2.0はまだ公開されていなかったことになるため、最新バージョンを確実に使いたい場合はnpx @pulumi/mcp-server@latestでnpm版を明示的に指定する形が確実です。

提供されるツール

ツールは大きく2系統に分かれます。Pulumi Registryを検索する読み取り系と、実際にPulumi CLIを実行する操作系です。

Pulumi CLI系のツール(pulumi-cli-preview・pulumi-cli-up・pulumi-cli-refresh)は、ローカルのPulumiプロジェクトに対して実際にコマンドを実行します。Terraform MCPサーバーがRegistryドキュメントの検索を主軸にしているのに対し、@pulumi/mcp-serverはCLI操作そのものをAIに委ねられる点が特徴です。

Registry系のツールはPulumiプロバイダーが公開しているリソース・関数・型情報を検索します。「AWS Lambda関数を作りたい」と伝えると、pulumi-registry-list-resourcesでLambda関連リソースを見つけ、pulumi-registry-get-resourceで必要なプロパティとコード例を取得し、複雑な入力型があればpulumi-registry-get-typeでスキーマを確認する、という流れでコードが組み立てられます。

pulumi-cli-previewはデプロイ前の差分確認に使います。実行結果を見ないままpulumi-cli-upを呼ばせるのではなく、必ずpreviewの内容を確認してからupに進む運用が安全です。MCPサーバー経由でAIにインフラ操作を任せる際の一般的な権限設計はMCPセキュリティガイドにまとめています。pulumi-cli-refreshは、クラウドのコンソール操作などでリソースが手動変更された場合に、Pulumiの状態ファイルと実際の構成のずれ(ドリフト)を検出・同期します。pulumi-cli-stack-outputはデプロイ完了後のURLやエンドポイント、リソースIDといった出力値を取得するためのツールで、次の作業(動作確認やDNS設定)にそのままつなげられます。

pulumi-resource-searchは、単一プロジェクトの枠を超えてクラウド全体のデプロイ済みリソースを検索・分析します。「未使用のS3バケットを一覧化して」のような棚卸し作業に向きます。neo-task-launcherはPulumi Neo(Pulumiが提供する自律実行エージェント)にタスクを渡すツールで、Pulumi Cloudのアカウントと連携している場合に使えます。

利用可能なプロンプトとしてはdeploy-to-awsがあり、書き終えたアプリケーションをAWSへデプロイする手順をセキュリティ・コスト最適化の観点付きでガイドします。

インストール前提

Pulumi CLI自体がクライアントマシンにインストールされている必要があります。Docker経由で動かす場合のみ、この前提は不要です(コンテナ内にCLIが同梱されるため)。既にPulumiでプロジェクトを運用しているチームであれば、CLIは既に手元にあるはずなので、追加のインストール作業は発生しません。逆にPulumi自体を使ったことがない場合は、先にCLIのセットアップとログインを済ませておく必要があります。

Claude Codeへの追加方法

claude mcp add -s user pulumi -- npx @pulumi/mcp-server@latest stdio

npx経由がもっとも手早い導入方法です。Node.jsとPulumi CLIがあらかじめインストール済みであれば、追加のセットアップは不要です。

Docker版を使う場合はイメージをpullしてから、mcpServers設定にコンテナ起動コマンドを渡します。

docker pull mcp/pulumi:latest

{
  "mcpServers": {
    "pulumi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "~/projects/my-pulumi-app:/app/project",
        "-e", "PULUMI_ACCESS_TOKEN=your-access-token",
        "mcp/pulumi:latest", "stdio"
      ]
    }
  }
}

pulumi-cli-previewやpulumi-cli-upはローカルのプロジェクトファイルを読み込む必要があるため、Docker版で使う場合は-vオプションでプロジェクトディレクトリをマウントします。マウント先は/app/project固定で、MCPツール呼び出し時も常にこのパスを参照します。~/.pulumiディレクトリもマウントしておくと、Pulumi CLIの認証情報・設定が保持されます。

環境変数

Registryのリソース・関数を検索するだけならPULUMI_ACCESS_TOKENは不要です。実際にデプロイ(pulumi-cli-up)したり、pulumi-resource-searchでクラウド横断検索したりする場合に必要になります。トークンはPulumiダッシュボードのAccess tokensページから発行でき、Docker版・npx版のどちらを使う場合でも同じ環境変数名で渡します。

ホスト型MCPサーバーとの違い

Pulumi公式ドキュメント(pulumi.com/docs)が案内しているのは、https://mcp.ai.pulumi.com/mcpというホスト型のMCPサーバーです。これは本記事で扱った@pulumi/mcp-server(npmパッケージ・ローカルstdio実行)とは別物です。公式ドキュメントが対応クライアントとして挙げているのはCursor・Claude Code・Windsurf・Claude Desktop、およびOAuthに対応する任意のMCPクライアントです。

Pulumi Neoは、Pulumiが提供するAI駆動のインフラエンジニアリングエージェントです。「全てのS3バケットのセキュリティ問題を洗い出してPRを作って」のような複雑な指示を渡すと、Neo自身が計画を立てて自律的に実行し、進捗を追跡できるリンクを返します。npm版のneo-task-launcherもこのNeoにタスクを渡せますが、Pulumi Cloudアカウントとの連携が前提になる点は共通です。

Claude Codeでホスト型を使う場合は、コマンドも異なります。

claude mcp add --transport http pulumi https://mcp.ai.pulumi.com/mcp

追加後は/mcpスラッシュコマンドでpulumiを選び、ブラウザ経由で認証します。「ローカルのPulumiプログラムをpreview・upしたい」なら@pulumi/mcp-server、「組織のPulumi Cloud上のスタックを横断的に検索・分析したい、あるいはNeoに複雑なタスクを任せたい」ならホスト型、という使い分けになります。

よくあるつまずき

pulumi-cli-previewやpulumi-cli-upが「プロジェクトが見つからない」と失敗する。Docker版でプロジェクトディレクトリをマウントし忘れているケースがほとんどです。ローカルインストール版(npx)であれば、Claude Codeを起動したディレクトリがそのままPulumiプロジェクトのルートとして扱われます。

Registry検索はできるがデプロイができない。PULUMI_ACCESS_TOKENが未設定の状態です。読み取り専用のpulumi-registry-*系ツールはトークンなしで動きますが、pulumi-cli-upのようなデプロイ系はPulumi Cloudとの通信が必要です。エラーメッセージが認証関連かどうかを確認し、トークンの有効期限が切れていないかもPulumiダッシュボード側で確認します。

「Pulumi MCPサーバーを追加して」と言われて公式ドキュメントの手順どおりに設定したのに、preview・upのツールが出てこない。公式ドキュメントの主要な案内先が、本記事の@pulumi/mcp-serverとは別のホスト型サーバーに切り替わっているためです。ローカルCLIの操作をさせたい場合は、npx @pulumi/mcp-server@latest stdioを明示的に指定する必要があります。

Claude Desktopでnpx版を使おうとしたらコマンドが見つからない。commandにnpx、argsに["@pulumi/mcp-server@latest", "stdio"]と分けて書く形式(Claude Codeの-- npx ...という1行のコマンド指定とは書き方が違う)なので、他クライアント向けの設定例をそのままClaude Codeの.mcp.jsonにコピーすると構文が合わないことがあります。

まとめ

@pulumi/mcp-serverは、ローカルのPulumiプロジェクトに対してpreview・up・refreshといったCLI操作を直接実行できる、npm配布の軽量なMCPサーバーです。Registry検索だけならトークン不要で、Claude Codeへの追加もnpxコマンド1行で済みます。個人開発や小規模なプロジェクトで、Claude Codeにインフラのデプロイまで任せたい場合に向きます。

一方、Pulumi公式が前面に案内しているのは、組織のPulumi Cloudリソースを横断検索しNeoに自動化タスクを委任できるホスト型サーバーです。両者は名前は同じでも実行場所・認証方式・できることが異なるため、「ローカルでCLIを動かしたいのか」「クラウド上の既存インフラを照会・分析したいのか」を先に決めてから選ぶと迷いません。どちらも試してみて、用途に応じて使い分ける、あるいは両方を併用するという選択肢もあります。