PowerShell module for implementing an MCP server

PWSH MCP — Build and expose PowerShell automation as MCP tools on demand.

Table of Contents

• Description
• Features
• Architecture Overview
• Use Cases
• Requirements
• Compatibility
• Getting Started
• Documentation
• License
• References

Description

The PowerShell MCP module lets you build Model Context Protocol (MCP) servers directly from PowerShell functions.

Instead of writing a server from scratch, you define functionality as PowerShell functions and expose it to MCP clients through JSON-RPC 2.0 over stdio transport.

This approach is useful for development, infrastructure management, and CI/CD automation scenarios where PowerShell scripts already exist and need to be exposed as structured tools for AI assistants.

Why PowerShell for MCP Servers:

PowerShell is well-suited for implementing MCP servers for automation processes because it combines a rich automation ecosystem with native cross-platform capabilities.

• Large module ecosystem – You can reuse existing PowerShell modules (Azure, AWS, VMware, Active Directory, Exchange, and many others) to quickly extend MCP server capabilities without rewriting existing automation.
• Cross-platform integration – PowerShell runs natively on Windows, Linux, and macOS, making it easy to deploy the same MCP server in different environments.
• Reuse of existing scripts – Many automation workflows already exist as PowerShell scripts or functions; the module allows you to expose them as MCP tools with minimal changes.
• Easy testability – PowerShell functions can be tested independently with Pester before wiring them into MCP, simplifying debugging and iterative development.
• Strong parameter validation – Built-in parameter attributes provide declarative input validation, reducing boilerplate and runtime errors from invalid inputs and improving tool reliability.
• Metadata-driven documentation – Comment-Based Help and parameter attributes let you keep function documentation and MCP schemas in sync. The same metadata is used both for human-readable help and for automatic JSON Schema generation.

Features

• Pure PowerShell implementation – no external runtime dependencies, leverages native PowerShell capabilities.
• Stdio-based MCP server – stdio transport implementation for integration with MCP clients such as GitHub Copilot and Gemini CLI.
• Cross-platform support – consistent behavior across platforms (Windows, Linux, macOS) with the same codebase.
• Automatic schema generation – converts PowerShell function parameters, validation attributes, and Comment-Based Help into JSON Schema definitions for MCP tools.
• Parameter validation – leverages PowerShell's declarative validation attributes for type-safe MCP tool inputs.

Architecture Overview

The module implements the MCP lifecycle on top of stdio and JSON-RPC 2.0:

• stdio transport – Communication happens exclusively through stdin/stdout; no HTTP endpoints are required.
• JSON-RPC 2.0 – Requests and responses follow the JSON-RPC 2.0 specification with strict validation and predictable error codes.
• Tool discovery (tools/list) – Discovers and exports selected PowerShell functions as MCP tools, including their schema and metadata.
• Tool execution (tools/call) – Incoming MCP tool calls are mapped to PowerShell function invocations, with automatic parameter binding and validation.
• Initialization and shutdown – Supports the core MCP methods.

Security considerations:

• Sanitization of incoming requests to prevent unintended command execution triggered by AI-generated inputs.
• Function parameter validation ensures that inputs match the expected types, ranges, and patterns.
• Leverages native PowerShell security features such as script signing and execution policies.
• The MCP server can be run inside a Docker container for additional isolation when exposing automation capabilities.

Use Cases

Typical scenarios include automating repetitive tasks, exposing existing scripts as tools for AI assistants, and integrating with local tools or cloud services:

Rapid tool development:

• Converting existing admin or maintenance scripts into reusable MCP tools.
• Prototyping developer utilities specific to a team or project.
• Building ad-hoc tools during a development session and immediately exposing them to AI coding assistants.

DevOps and CI/CD automation:

• Orchestrating deployment pipelines through MCP tools backed by existing PowerShell scripts.
• Exposing infrastructure-as-code workflows (Terraform, Ansible) via PowerShell wrappers.
• Managing build artifacts, release gates, and deployment validation steps as MCP tools.

Infrastructure management:

• Managing cloud resources (Azure PowerShell, AWS Tools for PowerShell, Google Cloud modules).
• Automating on-premises environments: Active Directory, Exchange, VMware, network devices, and more.
• Implementing monitoring and alerting workflows using existing PowerShell-based monitoring modules.

Enterprise automation:

• Integrating with external systems via REST or SDK-based PowerShell modules.
• Implementing compliance checks and audit pipelines using security-focused PowerShell modules.
• Generating reports and analytics by combining data-processing cmdlets with MCP tooling.

Requirements

• PowerShell 7.5 or later (cross-platform)
• MCP client that supports stdio transport (Visual Studio Code with GitHub Copilot, Gemini CLI, Copilot CLI).

Compatibility

Any MCP-compliant client that implements the MCP stdio transport and the core MCP methods should be able to connect to a PowerShell MCP server with appropriate configuration.

The repository currently includes documentation and examples for the following MCP clients:

• GitHub Copilot – AI coding assistant.
• GitHub Copilot CLI – command-line interface for GitHub Copilot.
• Gemini CLI – command-line AI assistant with MCP support.
• Claude Desktop – AI assistant.

Getting Started

The project includes ready-to-use samples and configuration templates for a quick start. For detailed usage and advanced configuration, refer to the user guide and developer guide.

1. Ensure prerequisites are installed (see Requirements).
2. Create a PowerShell-based MCP server.
3. Add an MCP server configuration entry to your MCP client.
4. Call the MCP tools from the MCP client.

Install-Module -Name pwsh.mcp

# Import the MCP server module
Import-Module pwsh.mcp -Force -ErrorAction Stop

# Define a simple echo function
function get_echo {
    [CmdletBinding()]
    param (
      [Parameter(Mandatory = $false, HelpMessage = "Text to echo")]
      [string] $text = "Lorem Ipsum"
    )
    return "Echo, $text!"
}

# Start the MCP server and pass the functions to expose.
New-MCPServer -FunctionInfo (Get-Item Function:get_echo)

{
  "servers": {
    "mcp-pwsh-server": {
      "type": "stdio",
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-NoLogo",
        "-File",
        "${workspaceFolder}/path/to/your/script.ps1"
      ]
    }
  }
}

#get_echo text="Hello, MCP!"

Documentation

• User Guide – detailed usage documentation, including advanced configuration, schema generation, and best practices.
• Developer Guide – contribution guidance, including coding standards, testing, and CI/CD processes.

References

• Model Context Protocol Specification
• PowerShell
• PowerShell Documentation
• PowerShell Cmdlet Development Guidelines
• Visual Studio Code
• GitHub Copilot CLI
• Gemini CLI

License

This project is licensed under the MIT License.