Overview

The Pulumi MCP Server is a lightweight HTTP service that automates Pulumi stack management by talking to the Pulumi REST API. It provides API endpoints to create stacks and list existing stacks for a Pulumi organization/project so other tools (CI pipelines, chatbots, or model-driven agents) can manage infrastructure stacks programmatically.

This server is useful when you want to provide a simple, auditable surface for automated workflows to create ephemeral environments, manage workspace lifecycles, or query existing stacks without embedding Pulumi credentials into many separate services. It centralizes access to the Pulumi API and can be deployed alongside CI/CD tooling or internal developer platforms.

Features

Create new Pulumi stacks scoped to an organization and project
List stacks for a given Pulumi organization/project
Simple HTTP JSON API suitable for automation and integration
Configurable via environment variables for tokens, org, project, and port
Minimal dependencies so it can run in containers or small VMs
Designed for use in CI/CD, preview environments, and orchestration systems

Installation / Configuration

There are two common deployment approaches: run with Node (or the provided runtime) or run inside Docker. Set these environment variables before running the server:

PULUMI_ACCESS_TOKEN — Pulumi API token with permissions to manage stacks
PULUMI_ORG — Pulumi organization name
PULUMI_PROJECT — Pulumi project name
PORT — HTTP port the server listens on (defaults to 3000)

Example Docker usage:

# Build (if repository contains a Dockerfile)
docker build -t pulumi-mcp-server .

# Run the server with environment variables
docker run -e PULUMI_ACCESS_TOKEN="x-pulumi-..." \
           -e PULUMI_ORG="my-org" \
           -e PULUMI_PROJECT="my-project" \
           -p 3000:3000 \
           pulumi-mcp-server

Example local run (Node.js runtime assumed):

# Install dependencies and run
npm install
PULUMI_ACCESS_TOKEN="x-pulumi-..." \
PULUMI_ORG="my-org" \
PULUMI_PROJECT="my-project" \
PORT=3000 \
node server.js

Tips:

Store PULUMI_ACCESS_TOKEN in a secrets manager or CI secret store; avoid checking it into source control.
Ensure the token has sufficient scope to create and list stacks in the specified org/project.

Available Resources

The server exposes a compact REST API. Below is a summary of commonly available endpoints, request fields, and example responses.

Endpoints

Method	Path	Description
POST	/stacks	Create a new Pulumi stack
GET	/stacks	List stacks for configured org/project

Create stack — request JSON fields

{
  "name": "feature-123",
  "description": "Ephemeral preview environment",
  "cloud": "aws"            // optional metadata
}

Create stack — example curl

curl -X POST http://localhost:3000/stacks \
  -H "Content-Type: application/json" \
  -d '{"name":"feature-123","description":"CI preview"}'

Create stack — example response (200/201)

{
  "name": "feature-123",
  "id": "org/project/feature-123",
  "createdAt": "2026-04-09T12:34:56Z",
  "status": "created"
}

List stacks — example curl

curl http://localhost:3000/stacks

List stacks — example response

[
  {"name":"dev","id":"org/project/dev","createdAt":"2023-10-01T08:00:00Z"},
  {"name":"feature-123","id":"org/project/feature-123","createdAt":"2026-04-09T12:34:56Z"}
]

Behavior notes:

The server forwards requests to Pulumi’s REST API under the configured organization and project.
Errors from Pulumi (authentication, validation, rate limits) are relayed as HTTP error responses with JSON bodies.

Use Cases

CI/CD: Automatically create a stack for each pull request, run a preview/apply, then tear it down when the branch is closed. Example: the CI job calls POST /stacks with a PR id to provision preview infra.
Ephemeral Environments: Provide one-command ephemeral environments for QA or demos. A web UI or chatbot can call the create endpoint and return a URL when the preview is ready.
Self-Service Developer Platform: Integrate with an internal developer portal so engineers can spin up sandboxes without direct access to Pulumi tokens.
Auditable Automation: Centralize Pulumi interactions behind a single service to add logging, RBAC, and monitoring for stack operations.

Security & Best Practices

Never embed PULUMI_ACCESS_TOKEN in client-side code. Keep it on the server or in a secret store.
Limit token scope and rotate regularly.
Run the server behind an authenticated gateway if you expose it internally; add RBAC and audit logging for production.
Respect Pulumi API rate limits and implement retry/backoff if you integrate heavy automation.

Links & Further Reading

Project repository: https://github.com/dogukanakkaya/pulumi-mcp-server
Pulumi REST API docs: https://www.pulumi.com/docs/reference/service-api/ (refer to official docs for API details and scopes)

This server is intended as a small, practical component for automating Pulumi stack management. Use it as a building block for CI pipelines, developer platforms, or model-driven automation.

Pulumi MCP Server — Create and List Stacks