Pwsh Mcp Demo

PowerShell MCP Server Demo

[](https://github.com/PowerShell/PowerShell) [](https://modelcontextprotocol.io) [](LICENSE)

A lightweight, easy-to-understand demonstration of a Model Context Protocol (MCP) server implemented in PowerShell. This server exposes PowerShell system information and management capabilities through the standardized MCP interface, enabling AI assistants to interact with Windows environments.

Table of Contents

• [Overview](#overview)
• [Features](#features)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Configuration](#configuration)
• [Usage](#usage)
• [Available Tools](#available-tools)
• [Available Resources](#available-resources)
• [Example Prompts](#example-prompts)
• [Architecture](#architecture)
• [API Reference](#api-reference)
• [Troubleshooting](#troubleshooting)
• [Contributing](#contributing)
• [License](#license)
• [Support](#support)

Overview

This project demonstrates how to build a functional MCP (Model Context Protocol) server using PowerShell. The server communicates via JSON-RPC over stdin/stdout, making it compatible with MCP-enabled AI assistants like Claude Desktop, Cline, and other MCP clients.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely interact with local tools and data sources. This server implementation showcases:

• JSON-RPC 2.0 communication over stdio
• Tool exposure for PowerShell operations
• Resource management for workspace information
• Content-Length framing with JSON-lines fallback
• Minimal dependencies for easy understanding and modification

Why PowerShell?

PowerShell provides native access to Windows system information, making it ideal for:

• System administration tasks
• Module and service management
• Configuration inspection
• Cross-platform scripting (PowerShell Core)

Features

✨ Core Capabilities

• Profile Status Checking - Inspect PowerShell profile files across all scopes
• Module Discovery - List installed PowerShell modules with pattern filtering
• Service Management - Query Windows services by status with configurable limits
• Workspace Information - Access current directory, user, and environment details

🔧 Technical Features

• Dual Transport Modes - Supports Content-Length framing and JSON-lines
• Auto-Detection - Automatically detects transport protocol
• Debug Logging - Comprehensive logging to stderr for troubleshooting
• Error Handling - Robust error responses with JSON-RPC error codes
• Configurable Limits - Prevents resource exhaustion with sensible defaults

Prerequisites

Required Software

• PowerShell 7.0 or later (PowerShell Core)
• Download: PowerShell Releases
• Verify installation: pwsh --version

• MCP-Compatible Client (one of the following):
• Claude Desktop - Anthropic's desktop application
• Cline VSCode Extension
• Any MCP-compatible client supporting stdio transport

Operating System

• Windows 10/11 - Full functionality (all tools available)
• macOS/Linux - Partial functionality (profile and module tools only; service tool unavailable)

Optional Dependencies

• Visual Studio Code - For development and debugging
• Git - For cloning the repository

Installation

Option 1: Clone Repository

# Clone or download the repository to your local machine

# Navigate to the directory
cd pwsh-mcp-demo

# Verify the server script exists
Test-Path ./mcp-server.ps1

Option 2: Manual Download

1. Download [mcp-server.ps1](mcp-server.ps1) from this repository
2. Save it to a directory of your choice
3. Note the full path for configuration

Verify Installation

# Test the server responds to input
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | pwsh ./mcp-server.ps1

You should see a JSON response with server information.

Quick Start

Get the server running in under 5 minutes:

Step 1: Configure Your MCP Client

For Claude Desktop

Edit your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this server configuration:

{
  "mcpServers": {
    "pwsh-mcp-demo": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "C:/path/to/pwsh-mcp-demo/mcp-server.ps1"
      ],
      "env": {
        "MCP_DEBUG": "true",
        "MCP_TRANSPORT_MODE": "auto"
      }
    }
  }
}

Important: Replace C:/path/to/pwsh-mcp-demo/mcp-server.ps1 with the actual path to your server script.

For Cline (VSCode Extension)

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "pwsh-mcp-demo": {
      "type": "stdio",
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "${workspaceFolder}/mcp-server.ps1"
      ],
      "env": {
        "MCP_DEBUG": "true",
        "MCP_TRANSPORT_MODE": "auto"
      }
    }
  }
}

Step 2: Restart Your MCP Client

• Claude Desktop: Completely quit and restart the application
• Cline: Reload the VSCode window (Ctrl+Shift+P → "Developer: Reload Window")

Step 3: Test the Connection

Try these prompts in your MCP client:

Check my PowerShell profile status

List installed PowerShell modules matching Az*

Show me 10 running Windows services

If you see results, congratulations! Your MCP server is working. 🎉

Configuration

Environment Variables

The server supports several environment variables for customization:

| Variable | Values | Default | Description | | :------------------- | :-------------------------------- | :------ | :----------------------------- | | MCP_DEBUG | true, false, 1, 0 | true | Enable debug logging to stderr | | MCP_TRANSPORT_MODE | auto, content-length, jsonl | auto | Transport protocol mode |

Transport Modes Explained

• auto - Automatically detects Content-Length headers or falls back to JSON-lines
• content-length - Forces Content-Length framing (recommended for production)
• jsonl - Forces newline-delimited JSON (useful for manual testing)

Debug Logging

When MCP_DEBUG=true, the server writes detailed logs to stderr:

[2026-02-16 20:35:27.123] [STARTUP] Starting pwsh-mcp-demo 1.0.0
[2026-02-16 20:35:27.456] [INFO] Received: {"jsonrpc":"2.0","id":1,"method":"initialize"...}
[2026-02-16 20:35:27.789] [INFO] Sent: {"jsonrpc":"2.0","id":1,"result":{...}}

Tip: Disable debug logging in production for better performance:

"env": {
  "MCP_DEBUG": "false"
}

Execution Policy

The server uses -ExecutionPolicy Bypass to ensure scripts run without policy restrictions. This is safe because:

• The server only executes its own code
• No external scripts are loaded
• User input is validated and sanitized

Usage

Available Tools

The server exposes three PowerShell tools through the MCP interface:

1. get_powershell_profile_status

Retrieves information about PowerShell profile files across all scopes.

Parameters: None

Returns: JSON array with profile information including:

• Profile scope name
• Full file path
• Existence status
• File size (if exists)
• Last modified timestamp (if exists)

Example Output:

[
  {
    "profile": "CurrentUserCurrentHost",
    "path": "C:\\Users\\YourName\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1",
    "exists": true,
    "length": 2048,
    "lastWriteTime": "2026-02-15T10:30:00"
  },
  {
    "profile": "AllUsersAllHosts",
    "path": "C:\\Program Files\\PowerShell\\7\\profile.ps1",
    "exists": false,
    "length": null,
    "lastWriteTime": null
  }
]

2. list_installed_modules

Lists installed PowerShell modules with optional wildcard filtering.

Parameters:

| Parameter | Type | Required | Description | | :------------ | :----- | :------- | :---------------------------------------- | | namePattern | string | No | Wildcard pattern (e.g., Az*, Pester*) |

Returns: JSON array of modules (max 200) with:

• Module name
• Version number
• Module base path
• PowerShell edition compatibility

Example Output:

[
  {
    "Name": "Az.Accounts",
    "Version": "2.15.1",
    "ModuleBase": "C:\\Program Files\\PowerShell\\Modules\\Az.Accounts\\2.15.1",
    "PSEdition": "Core"
  },
  {
    "Name": "Az.Storage",
    "Version": "6.1.0",
    "ModuleBase": "C:\\Program Files\\PowerShell\\Modules\\Az.Storage\\6.1.0",
    "PSEdition": "Core"
  }
]

3. get_windows_services

Queries Windows services with status filtering and result limiting.

Parameters:

| Parameter | Type | Required | Description | | :-------- | :------ | :------- | :------------------------------------------------------ | | status | string | No | Filter: all, running, or stopped (default: all) | | limit | integer | No | Max results: 1-200 (default: 25) |

Returns: JSON array of services with:

• Service name
• Display name
• Current status
• Service type

Example Output:

[
  {
    "Name": "EventLog",
    "DisplayName": "Windows Event Log",
    "Status": 4,
    "ServiceType": 16
  },
  {
    "Name": "Winmgmt",
    "DisplayName": "Windows Management Instrumentation",
    "Status": 4,
    "ServiceType": 16
  }
]

Note: Status codes: 1 = Stopped, 4 = Running

Available Resources

workspace://info

Provides current workspace and environment information.

URI: workspace://info

MIME Type: application/json

Returns:

{
  "currentDirectory": "C:\\Users\\YourName\\Projects\\pwsh-mcp-demo",
  "timestamp": "2026-02-16 20:35:27",
  "environment": {
    "user": "YourName",
    "computer": "DESKTOP-ABC123"
  }
}

Example Prompts

Use these natural language prompts with your MCP client to interact with the server:

Profile Management

Check my PowerShell profile files and tell me which ones exist

Show me the size and last modified date of my PowerShell profiles

Module Discovery

List all installed PowerShell modules matching Az*

What PowerShell modules are installed on this system?

Service Management

List 25 running Windows services

Show me 50 stopped services

Get 10 services regardless of status

Workspace Information

Read workspace://info and show me the current directory

What's my current workspace information?

Multi-Step Operations

First check my PowerShell profiles, then list Az* modules, and summarize both

Get workspace info and list 15 running services, then create a system report

Architecture

High-Level Design

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│                  (Claude Desktop / Cline)                   │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over stdio
                         │ (Content-Length or JSON-lines)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                   PowerShell MCP Server                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Transport Layer                        │  │
│  │  • Read-Message (stdin)                            │  │
│  │  • Write-Response (stdout)                         │  │
│  │  • Content-Length detection                        │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Request Router                         │  │
│  │  • Invoke-Request (method dispatcher)              │  │
│  │  • JSON-RPC validation                             │  │
│  │  • Error handling                                  │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Business Logic                         │  │
│  │  • Invoke-Tool (tool implementations)              │  │
│  │  • Get-ResourceContent (resource handler)          │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              PowerShell APIs                        │  │
│  │  • $PROFILE (profile paths)                        │  │
│  │  • Get-Module (module listing)                     │  │
│  │  • Get-Service (service queries)                   │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Request Lifecycle

1. Read - Server reads JSON-RPC request from stdin
2. Parse - Request is parsed and validated as JSON
3. Route - Method is dispatched to appropriate handler
4. Execute - Tool or resource logic runs
5. Respond - JSON-RPC response is written to stdout

Key Components

| Component | Purpose | Location | | :-------------------- | :--------------------- | :------------ | | Start-McpServer | Main server loop | Lines 497-531 | | Read-Message | Transport layer input | Lines 214-268 | | Write-Response | Transport layer output | Lines 270-285 | | Invoke-Request | Method dispatcher | Lines 381-495 | | Invoke-Tool | Tool implementations | Lines 287-361 | | Get-ResourceContent | Resource handler | Lines 363-374 |

Design Principles

• Simplicity - Minimal abstractions, easy to understand
• Explicitness - Clear function names and control flow
• Modularity - Separate concerns (transport, routing, logic)
• Robustness - Comprehensive error handling
• Debuggability - Detailed logging for troubleshooting

API Reference

Supported MCP Methods

| Method | Type | Description | | :-------------------------- | :----------- | :-------------------------------------- | | initialize | Request | Initialize MCP session | | initialized | Notification | Session initialization complete | | notifications/initialized | Notification | Alternative initialization notification | | notifications/cancelled | Notification | Operation cancellation | | tools/list | Request | List available tools | | tools/call | Request | Execute a tool | | resources/list | Request | List available resources | | resources/read | Request | Read a resource |

JSON-RPC Error Codes

| Code | Meaning | When Used | | :------- | :--------------- | :------------------------- | | -32700 | Parse error | Invalid JSON received | | -32600 |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cviorel
• Source: cviorel/pwsh-mcp-demo
• License: MIT

Install and usage instructions live in the source repository linked above.