Skip to content

Commit 17f3d73

Browse files
vova-ivanovvova-ivanov
committed
Separated HTTP implementation concerns from README
1 parent 93f6341 commit 17f3d73

File tree

1 file changed

+122
-73
lines changed

1 file changed

+122
-73
lines changed

‎README.md

Lines changed: 122 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -4,49 +4,86 @@
44
<img width="380" height="200" src="https://glama.ai/mcp/servers/@pulumi/mcp-server/badge" />
55
</a>
66

7-
> **Note:** This MCP server is currently under active development. Its API (including available commands and their arguments) is experimental and may introduce breaking changes without notice. Please file an issue on [GitHub](https://github.com/pulumi/mcp-server/issues) if you encounter bugs or need support for additional Pulumi commands.
7+
The Pulumi Model Context Protocol Server enables advaced Infrastructure as Code development capabilities for connected agents.
88

9-
A server implementing the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) for interacting with Pulumi CLI using the Pulumi Automation API and Pulumi Cloud API.
9+
## Features
1010

11-
This package allows MCP clients to perform Pulumi operations like retrieving package information, previewing changes, deploying updates, and retrieving stack outputs programmatically without needing the Pulumi CLI installed directly in the client environment.
11+
### Available Tools
1212

13-
## Usage
13+
| Tool | Description |
14+
|------|-------------|
15+
| `pulumi-registry-list-resources` | Browse available cloud resources to discover what infrastructure components can be deployed |
16+
| `pulumi-registry-list-functions` | Explore available provider functions for interacting with cloud resources |
17+
| `pulumi-registry-get-resource` | Get code examples and documentation for specific resources that can be deployed |
18+
| `pulumi-registry-get-function` | Access examples of provider functions for usage in your Pulumi program |
19+
| `pulumi-registry-get-type` | Get schema definitions needed to properly set up complex resource properties and types |
20+
| `pulumi-cli-preview` | Preview infrastructure changes before deployment, showing what resources will be created, updated, or deleted |
21+
| `pulumi-cli-up` | Deploy infrastructure changes to the cloud, creating and updating resources as defined in your Pulumi program |
22+
| `pulumi-cli-stack-output` | Retrieve deployment outputs like URLs and resource IDs from your infrastructure stacks |
23+
| `pulumi-cli-refresh` | Sync your Pulumi state with actual cloud resources to detect drift and manual changes |
24+
| `pulumi-resource-search` | Discover, count, and analyze your deployed infrastructure across all cloud providers. |
1425

15-
The Pulumi CLI has to be installed on you machine.
26+
### Available Prompts
1627

17-
This package is primarily intended to be integrated into applications that can use MCP servers as AI tools.
28+
| Prompt | Description |
29+
|--------|-------------|
30+
| `deploy-to-aws` | Get step-by-step guidance for deploying already written applications to the cloud with Pulumi, including security and cost optimization tips |
1831

19-
### Claude Code
32+
## Installation
2033

21-
For [Claude Code](https://claude.ai/code), you can install this MCP server using:
34+
### Requirements
35+
36+
1. **[Pulumi CLI](https://www.pulumi.com/docs/cli/)** must be installed on the client machine
37+
2. **[Docker](https://www.docker.com/)** (optional) - Required only for containerized deployment
38+
39+
### Usage with Claude Code
40+
41+
For [Claude Code](https://claude.ai/code), install the MCP server using:
2242

2343
```bash
2444
claude mcp add -s user pulumi -- npx @pulumi/mcp-server@latest stdio
2545
```
2646

27-
### Claude Desktop
47+
### Usage with Claude Desktop
2848

29-
For Claude Desktop, you can include Pulumi MCP Server in the MCP configuration file:
49+
For Claude Desktop, add the following configuration to your MCP config file:
3050

3151
```json
3252
{
3353
"mcpServers": {
3454
"pulumi": {
3555
"command": "npx",
36-
"args": ["@pulumi/mcp-server@latest","stdio"]
56+
"args": ["@pulumi/mcp-server@latest", "stdio"]
3757
}
3858
}
3959
}
4060
```
4161

42-
Or if you prefer HTTP with Server-Sent Events (SSE) instead of `stdio`:
62+
### Usage with VSCode
63+
64+
Create a file called `.vscode/mcp.json` in your workspace. Add the following section, and the MCP will become accessible to your assistant:
4365

4466
```json
4567
{
46-
"mcpServers": {
68+
"servers": {
4769
"pulumi": {
4870
"command": "npx",
49-
"args": ["@pulumi/mcp-server@latest","sse"]
71+
"args": ["@pulumi/mcp-server@latest", "stdio"]
72+
}
73+
}
74+
}
75+
```
76+
77+
Alternatively, you can add the following to your user configuration and be able to use the MCP server everywhere. You can open the configuration by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`:
78+
79+
```json
80+
{
81+
"mcp": {
82+
"servers": {
83+
"pulumi": {
84+
"command": "npx",
85+
"args": ["@pulumi/mcp-server@latest", "stdio"]
86+
}
5087
}
5188
}
5289
}
@@ -56,105 +93,117 @@ Or if you prefer HTTP with Server-Sent Events (SSE) instead of `stdio`:
5693

5794
For [Devin](https://app.devin.ai), you can set up the Pulumi MCP Server by:
5895

59-
1. Navigate to https://app.devin.ai/settings/mcp-marketplace/setup/pulumi
60-
2. Provide your Pulumi access token, which can be obtained from the Access tokens section in the sidebar of the Pulumi dashboard
61-
3. Click "Enable"
96+
1. Navigating to https://app.devin.ai/settings/mcp-marketplace/setup/pulumi
97+
2. Providing your Pulumi access token, which can be obtained from the Access tokens section in the sidebar of the Pulumi dashboard
98+
3. Clicking "Enable"
99+
100+
More about using the MCP server with other popular clients: [Pulumi MCP Server Documentation](https://www.pulumi.com/docs/iac/using-pulumi/mcp-server/).
62101

63-
## Docker Container
102+
## Docker Installation
64103

65-
You can also run the Pulumi MCP Server as a Docker container. This approach eliminates the need to install Node.js and the package dependencies directly on your host machine.
104+
The Pulumi MCP Server can additionally be run as a Docker container, eliminating the need to install Node.js and package dependencies directly on your host machine.
105+
106+
### Using the Official Image
107+
108+
Pull the official image built by Docker:
109+
110+
```bash
111+
docker pull mcp/pulumi:latest
112+
```
66113

67-
### Building the Container
114+
### Building Locally
68115

69-
To build the container:
116+
Or build the container with local changes:
70117

71118
```bash
72119
docker build -t pulumi/mcp-server:latest .
73120
```
74121

75-
### Using with MCP Clients
122+
### Usage With Agents
123+
124+
**STDIO Mode**
76125

77-
To use the containerized server with MCP clients, you'll need to configure the client to use the Docker container. For example, in Claude desktop's MCP configuration:
126+
Run the server in basic STDIO configuration:
78127

79128
```json
80129
{
81130
"mcpServers": {
82131
"pulumi": {
83132
"command": "docker",
84-
"args": ["run", "-i", "--rm", "pulumi/mcp-server:latest", "stdio"]
133+
"args": [
134+
"run", "-i", "--rm",
135+
"-e", "PULUMI_ACCESS_TOKEN=your-access-token",
136+
"mcp/pulumi:latest", "stdio"
137+
]
85138
}
86139
}
87140
}
88141
```
89142

90-
### Using with MCP Clients over HTTP (SSE)
143+
**With Local Project Access**
91144

92-
To use the containerized server with MCP clients over HTTP (SSE), you can run the container with the following command:
145+
For Pulumi CLI operations that require access to local projects and their files, mount the project directory:
93146

94147
```json
95148
{
96149
"mcpServers": {
97150
"pulumi": {
98151
"command": "docker",
99-
"args": ["run", "-i", "--rm", "-p", "3000:3000", "pulumi/mcp-server:latest", "sse"]
152+
"args": [
153+
"run", "-i", "--rm",
154+
"-v", "~/projects/my-pulumi-app:/app/project",
155+
"-e", "PULUMI_ACCESS_TOKEN=your-access-token",
156+
"mcp/pulumi:latest", "stdio"
157+
]
100158
}
101159
}
102160
}
103161
```
104162

163+
**Server-Sent Events (SSE) Mode**
105164

165+
Run as a standalone SSE server for real-time communication:
106166

107-
For Pulumi operations that require access to local Pulumi projects, you'll need to mount the appropriate directories. For example, if your Pulumi project is in `~/projects/my-pulumi-app`:
108-
109-
```json
110-
{
111-
"mcpServers": {
112-
"pulumi": {
113-
"command": "docker",
114-
"args": ["run", "-i", "--rm", "-v", "~/projects/my-pulumi-app:/app/project", "pulumi/mcp-server:latest"]
115-
}
116-
}
117-
}
167+
```bash
168+
docker run -i --rm \
169+
-p 3000:3000 \
170+
-e PULUMI_ACCESS_TOKEN=your-access-token \
171+
mcp/pulumi:latest sse
118172
```
119173

120-
Then when using the MCP tools, you would reference the project directory as `/app/project` in your requests.
174+
### Environment Variables
121175

122-
## Available Commands
176+
| Variable | Description | Default | Required |
177+
|----------|-------------|---------|----------|
178+
| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token | `""` | For resource deployment & insights |
123179

124-
The server exposes handlers for the following Pulumi operations, callable via MCP requests:
180+
> **Notes:**
181+
> - When mounting local directories, reference the project as `/app/project` in your MCP tool requests
182+
> - Mount `~/.pulumi` to preserve Pulumi CLI configuration and credentials
183+
> - Add cloud provider credential volumes and environment variables as needed for your deployments
125184
126-
* **`preview`**: Runs `pulumi preview` on a specified stack.
127-
* `workDir` (string, required): The working directory containing the `Pulumi.yaml` project file.
128-
* `stackName` (string, optional): The stack name to operate on (defaults to 'dev').
129-
* **`up`**: Runs `pulumi up` to deploy changes for a specified stack.
130-
* `workDir` (string, required): The working directory containing the `Pulumi.yaml` project file.
131-
* `stackName` (string, optional): The stack name to operate on (defaults to 'dev').
132-
* **`stack-output`**: Retrieves outputs from a specified stack after a successful deployment.
133-
* `workDir` (string, required): The working directory containing the `Pulumi.yaml` project file.
134-
* `stackName` (string, optional): The stack name to retrieve outputs from (defaults to 'dev').
135-
* `outputName` (string, optional): The specific stack output name to retrieve. If omitted, all outputs for the stack are returned.
136-
* **`get-resource`**: Returns information about a specific Pulumi Registry resource, including its inputs and outputs.
137-
* `provider` (string, required): The cloud provider (e.g., 'aws', 'azure', 'gcp', 'random') or `github.com/org/repo` for Git-hosted components.
138-
* `module` (string, optional): The module to query (e.g., 's3', 'ec2', 'lambda').
139-
* `resource` (string, required): The resource type name (e.g., 'Bucket', 'Function', 'Instance').
140-
* **`list-resources`**: Lists available resources within a Pulumi provider package, optionally filtered by module.
141-
* `provider` (string, required): The cloud provider (e.g., 'aws', 'azure', 'gcp', 'random') or `github.com/org/repo` for Git-hosted components.
142-
* `module` (string, optional): The module to filter by (e.g., 's3', 'ec2', 'lambda').
143-
* **`deploy-to-aws`**: Deploy application code to AWS by generating Pulumi infrastructure. Automatically provisions AWS resources (S3, Lambda, EC2, etc.) based on application type.
144-
* No parameters required - the tool analyzes the current working directory to understand the application structure and generate appropriate infrastructure code.
185+
## Development
145186

146-
## Available Prompts
187+
### Requirements
188+
- Node.js and npm
189+
- Pulumi CLI
147190

148-
The server also provides prompts that can be used by MCP clients:
191+
### Build Commands
149192

150-
* **`deploy-to-aws`**: AWS deployment guidance prompt that provides comprehensive instructions for analyzing application code and generating Pulumi infrastructure-as-code for AWS deployments. Includes best practices for security, cost optimization, and multi-environment setups.
193+
| Command | Description |
194+
|---------|-------------|
195+
| `make ensure` | Install dependencies |
196+
| `make build` | Build the project |
197+
| `make test` | Run all tests |
198+
| `npm run build` | Build using npm |
199+
| `npm run lint:fix` | Find and fix lint errors |
151200

152-
## Development
201+
### Quick Start
153202

154-
1. Clone the repository.
155-
2. Install dependencies: `make ensure`
156-
3. Build the project: `make build`
157-
4. Test the project: `make test`
203+
1. Clone the repository
204+
2. Install dependencies: `make ensure`
205+
3. Build the project: `make build`
206+
4. Test the project: `make test`
158207

159208
### How to Install Locally
160209

@@ -194,18 +243,18 @@ Replace `/path/to/your/mcp-server` with the absolute path to your local reposito
194243

195244
### List existing tools
196245

197-
Use MCP Inspector to list the existing tools and their metadata:
246+
Use MCP Inspector to list the capabilities:
198247

199248
```bash
249+
# List tools and their metadata
200250
npm run inspector -- --method tools/list
201-
```
202-
203-
Use MCP Inspector to list the existing prompts and their metadata:
204251

205-
```bash
252+
# List prompts and their metadata
206253
npm run inspector -- --method prompts/list
207254
```
208255

256+
> **Note:** This MCP server is actively evolving with new features being added regularly. While we strive to maintain compatibility, some API changes may occur as we improve it. Please file an issue on [GitHub](https://github.com/pulumi/mcp-server/issues) if you encounter bugs or would like to request support for additional Pulumi commands.
257+
209258
## License
210259

211260
This project is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)