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

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

「Pulumi MCPサーバー」という名前は、もう1つあります。Pulumi Cloudに接続し、Neo(自律実行エージェント)へタスクを委任するOAuth認証のホスト型サーバーです。Pulumiの公式ドキュメントがいま案内しているのはこちらで、両者は設定もできることも別物です。

まず決める: ローカルでCLIを動かすか、クラウド上の情報を引くか

どちらを入れるかは、AIに何をさせたいかで決まります。

両方を同時に登録することもできます。サーバー名を変えれば(たとえばpulumiとpulumi-hosted)、同じ.mcp.jsonに並べられます。

導入の流れ

ローカル版をClaude Codeで使い始めるまでの手順です。

Claude Codeへの追加

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

Pulumi公式のREADMEが示している追加コマンドです。-s userは全プロジェクトで使うユーザースコープです。省略すると現在のプロジェクト向けのlocalスコープになります。v2.1.289のclaude mcp add --helpでも、スコープの既定値はlocalです。

チームで同じ設定を共有したいときは、-s projectを指定します。v2.1.289では次の.mcp.jsonが生成されます。

{
  "mcpServers": {
    "pulumi": {
      "type": "stdio",
      "command": "npx",
      "args": ["@pulumi/mcp-server@latest", "stdio"],
      "env": {}
    }
  }
}

アクセストークンを同時に渡す場合は、-eをサーバー名の後ろに置きます。

claude mcp add pulumi -s project -e PULUMI_ACCESS_TOKEN=<your-token> -- npx @pulumi/mcp-server@latest stdio

-eは複数の値を受け取る形式なので、サーバー名より前に-e KEY=値を書くと、名前が環境変数の値として読まれます。-e PULUMI_ACCESS_TOKEN=... pulumi2 -- npx ...の順に書くと、Invalid environment variable format: pulumi2で止まり、.mcp.jsonは更新されません。名前を先頭に置いた上のコマンドなら、生成物のenvにPULUMI_ACCESS_TOKENが入ります。

-s projectで共有する.mcp.jsonにトークンの実値を書くと、リポジトリに混入します。値は環境変数から渡す運用を選ぶ手もあります。MCP経由でAIにインフラを触らせるときの権限設計は、MCPセキュリティガイドで扱っています。

Docker版を使う

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

READMEの注記は3点です。ローカルのプロジェクトを扱うときは-vでマウントし、MCPツールの呼び出しでは/app/projectを参照します。~/.pulumiをマウントすると、Pulumi CLIの設定と認証情報が残ります。クラウドプロバイダーの認証情報は、ボリュームや環境変数を足して渡します。

Docker Hubの説明には、このイメージは「Docker Inc.がビルドしたもの」と書かれています。

提供されるツール

ツールは、Pulumi Registryを引く読み取り系と、Pulumi CLIを実行する操作系に分かれます。

プロンプトはdeploy-to-awsが1つです。書き終えたアプリケーションをAWSへ載せる手順を、セキュリティとコスト最適化のヒント付きで案内します。

pulumi-cli-*の4つは、ローカルのPulumiプロジェクトで実際にコマンドを走らせます。Terraform MCPサーバーはRegistryドキュメントの検索が主軸です。こちらはCLI操作そのものをAIに渡せる点が違いです。

ホスト型のページの例では、「AWS Lambda関数を作りたい」と頼むと、まずlist-resourcesでLambda関連のリソースを探し、次にget-resourceでプロパティとコード例を引きます。ローカル版のpulumi-registry-get-typeは、複雑なリソースプロパティのスキーマ定義を取得するツールです。

操作系は順番が大事です。pulumi-cli-previewの結果を読んでからpulumi-cli-upに進めます。pulumi-cli-refreshは、コンソールで手動変更されたリソースとPulumiの状態のずれ(ドリフト)を検出・同期します。pulumi-cli-stack-outputは、デプロイ後のURLやリソースIDを、動作確認やDNS設定へ渡すときに使います。pulumi-resource-searchは、単一プロジェクトを越えた棚卸し(「未使用のS3バケットを一覧化して」のような依頼)向けです。

環境変数

READMEの環境変数表に載っているのは、次の1つです。

npx版でもDocker版でも、同じ変数名で渡します。

ホスト型との違い: 名前が同じ別のサーバー

Pulumi公式ドキュメントの「Pulumi Model Context Protocol server」のページが扱うのは、https://mcp.ai.pulumi.com/mcpのホスト型です。対応クライアントとして、Cursor・Claude Code・Windsurf・Claude Desktopが挙がっています。OAuthに対応するMCPクライアントなら使えます。

Claude Codeへの追加コマンドは、ローカル版と形が違います。

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

v2.1.289で同じ形のコマンドを実行すると、.mcp.jsonには"type": "http"とurlだけが入り、commandもenvもありません。追加後はClaude Code上で/mcpを開き、pulumiを選んで接続します。ブラウザが開くので、Pulumiのアクセストークンを入力し、組織を選びます。

ツール名もローカル版とは別系統です。ホスト型のページに載っているツールを、ローカル版と対応づけると次のようになります。

ホスト型のNeo用ツールは、neo-get-tasks(タスク一覧)・neo-continue-task(別のタスクへ切り替え)・neo-reset-conversation(会話文脈のリセット)の3つです。

プロンプトも広がっています。ホスト型のページには、deploy-to-awsのほかに、Terraform HCLをPulumi TypeScriptへ変えるconvert-terraform-to-typescriptが載っています。AWS CDKからの移行用には、cdk-migration-plan・cdk-migration-automated・cdk-migration-manual・cdk-migration-troubleshootの4つがあります。既存のIaCをPulumiへ移す作業が目的なら、入口はこちらです。

Neoは、Pulumiが提供するAI駆動のインフラエンジニアリングエージェントです。「全てのS3バケットのセキュリティ問題を洗い出してPRを作って」のような依頼を渡すと、Neoが計画を立てて実行し、進捗を追えるリンクを返します。ローカル版のneo-task-launcherも、同じNeoにタスクを渡すツールです。

パッケージの現状

Docker版のlatestはnpm版0.2.0より3日早い更新なので、最新のnpm版を確実に使いたいときは、npx @pulumi/mcp-server@latestと明示する形が合っています。

npmのメタデータにdeprecatedの指定はなく、配布は続いています。一方、Docker Hubの説明がソースとして案内するGitHubのpulumi/mcp-serverは、未ログインでアクセスすると404を返します。未ログインで404になる理由(非公開・移転など)は、Docker Hubの説明からは分かりません。

よくあるつまずき

公式ドキュメントの手順どおりに設定したのに、preview・upのツールが出てこない。ドキュメントが案内するのはホスト型で、ツール一覧にCLI実行系がありません。ローカルのCLIを動かしたいなら、npx @pulumi/mcp-server@latest stdioを明示します。

Docker版でpulumi-cli-previewやpulumi-cli-upがプロジェクトを扱えない。READMEは、ローカルのプロジェクトを扱うときは-vでマウントし、/app/projectを参照するよう案内しています。マウントの有無をまず確かめます。

-eを付けたらInvalid environment variable formatと表示される。サーバー名の前に-eを置くと、名前が値として読まれます。

デプロイや検索でPulumi Cloudの認証エラーが出る。READMEはPULUMI_ACCESS_TOKENを、デプロイとインサイトの場面で必要としています。トークンの有効期限は、Pulumiダッシュボード側で確かめます。

Claude Desktopに入れるとき、Claude Codeの設定をそのまま貼って構文が合わない。Pulumi公式のREADMEは、Claude Desktopにはcommandにnpx、argsに["@pulumi/mcp-server@latest", "stdio"]と分けて書く形を示しています。Claude Codeの-- npx ...という1行指定とは書き方が別です。

まとめ

二つは競合せず、名前を分ければ同じ.mcp.jsonで併用できます。併用するなら、pulumi-cli-upの前にpulumi-cli-previewの差分を読む段を、AIに任せる範囲の境目にしておくと判断が揃います。