Table of Contents

Getting Started with PoshMcp

Transform PowerShell into AI-consumable tools in minutes. This guide walks you through installing, configuring, and running PoshMcp.

Prerequisites

Required:

Optional:

  • PowerShell 7 — for out-of-process PowerShell support (better module isolation)
  • .NET 10 SDK — only needed if building from source
  • Docker — only needed for containerized deployments
  • Git — only needed if cloning the repository

Installation (5 minutes)

Install PoshMcp as a global .NET tool from nuget.org:

dotnet tool install -g poshmcp

Verify installation:

poshmcp --version

For a specific version:

dotnet tool install -g poshmcp --version 0.5.5

Option 2: Docker Container

For consistent environments and cloud deployment:

# Build the image
docker build -t poshmcp:latest https://github.com/microsoft/poshmcp.git

# Run the container
docker run -p 8080:8080 poshmcp:latest

Option 3: Building from Source

For developers and contributors:

git clone https://github.com/microsoft/poshmcp.git
cd poshmcp
dotnet build
dotnet run --project PoshMcp.Server -- serve --transport stdio

First Run (3 steps)

Step 1: Create Configuration

poshmcp create-config

This creates appsettings.json with sensible defaults.

Step 2: Expose Tools

Choose how to expose PowerShell commands:

Option A: Specific commands

poshmcp update-config --add-function Get-Process
poshmcp update-config --add-function Get-Service

Option B: Include patterns

poshmcp update-config --add-include-pattern "Get-*"

Option C: Modules

poshmcp update-config --add-module Az.Accounts
poshmcp update-config --add-import-module Az.Accounts

Step 3: Start the Server

For local development (VS Code, GitHub Copilot):

poshmcp serve --transport stdio

For HTTP API (testing, integration):

poshmcp serve --transport http --port 8080

Next: Configure for Your Use Case

Testing Your Setup

With Stdio Mode

Add this to your MCP client configuration (e.g., .vscode/cline_mcp_settings.json):

{
  "mcpServers": {
    "poshmcp": {
      "command": "poshmcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

With HTTP Mode

Test with curl:

# List available tools
curl http://localhost:8080/tools

# Call a tool
curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "Get-Process",
    "arguments": {}
  }'

# Health check
curl http://localhost:8080/health

Troubleshooting

Problem: No tools discovered

# Check configuration file
cat ./appsettings.json

# Verify PowerShell access
pwsh -Command "Get-Command Get-Process"

Problem: Server won't start

# Check .NET version
dotnet --version

# Check for port conflicts (HTTP mode)
lsof -i :8080  # macOS/Linux
Get-NetTCPConnection -LocalPort 8080  # Windows

Problem: Module installation fails

# Test module installation manually
pwsh -Command "Install-Module Az.Accounts -Force"

# Increase installation timeout
poshmcp update-config --install-timeout-seconds 600

Ready for more? → Configuration Guide

Edit this page