nopenix/powershell-mcp-server repository overview

⁠PowerShell MCP Server

A self-hosted Model Context Protocol (MCP) server that provides a sandboxed PowerShell environment for AI assistants.

⁠🚀 Quick Start

# Run the server (it will be available at http://localhost:8080)
docker run -d -p 8080:8080 --name mcp-server nopenix/powershell-mcp-server:latest

That's it! Your server is now running and ready to connect to AI tools.

⁠💡 What Is This For?

This server provides a sandboxed PowerShell environment that AI assistants can use to:

• ✅ Run PowerShell commands in an isolated environment
• ✅ Get organized results with success/failure information
• ✅ Handle errors gracefully and report them clearly
• ✅ See command output in a format that's easy for AI to understand
• ✅ Learn PowerShell syntax and capabilities

Important Note: This runs in a containerized, isolated environment - it does NOT have direct access to your host system's files, processes, or resources. It's perfect for learning PowerShell, testing commands safely, or running PowerShell-specific tasks in a controlled environment.

⁠🏗️ Under The Hood

This server is built on:

• Base Image: Microsoft's official PowerShell Docker image (mcr.microsoft.com/powershell:latest)
• Web Framework: Pode⁠ - A cross-platform PowerShell framework for REST APIs, Web Sites, and TCP/UDP servers
• Container Size: Lightweight (~400MB) for fast downloads and minimal resource usage
• Isolation: Runs in a secure container with no host filesystem access by default

The container includes:

• PowerShell 7+ with full .NET support
• Common PowerShell modules pre-installed
• Pode web framework for HTTP handling
• Structured JSON response formatting
• Built-in logging and error handling
• OpenAPI specification at /openapi.yaml for API documentation

⁠🤖 Connect to AI Assistants

⁠OpenWebUI Integration

1. Make sure your PowerShell MCP Server is running at http://localhost:8080
2. In OpenWebUI, go to Admin Settings → External Tools
3. Click + Add Server
4. Set Type to MCP (Streamable HTTP)
5. Enter Server URL: http://localhost:8080
6. Click Save and restart OpenWebUI if prompted

Now you can ask OpenWebUI to run PowerShell commands!

⁠VS Code Continue Integration

1. Make sure your PowerShell MCP Server is running at http://localhost:8080
2. In VS Code, open the Continue extension settings
3. Add the MCP server to your configuration (specific steps may vary by Continue version)

⁠Claude Desktop Integration

1. Make sure your PowerShell MCP Server is running at http://localhost:8080
2. In Claude Desktop settings, look for "Tools" or "External Tools"
3. Add a new MCP tool with URL: http://localhost:8080
4. Save and restart Claude

⁠🔧 How to Use

Once connected, you can ask your AI assistant to run PowerShell commands such as:

"Show me how to list files in PowerShell"
"Generate a random password using PowerShell"
"How do I work with JSON in PowerShell?"
"Show me PowerShell examples for string manipulation"
"What are the built-in PowerShell variables?"
"Help me understand PowerShell pipelines"
"What PowerShell commands are available for working with dates?"

Since this is a sandboxed environment, it's safe for experimentation and learning!

⁠🛡️ Security & Safety

✅ Sandboxed Environment: Runs in an isolated container, protecting your host system ✅ Safe Experimentation: Perfect for learning PowerShell without risk ✅ Controlled Access: No direct access to host files or processes ✅ Clear Logging: All commands executed are logged for visibility

⁠📝 Logging

The server provides comprehensive logging:

• Request Logging: All HTTP requests with status codes
• Error Logging: Detailed error information when commands fail
• Operation Logging: Clear messages showing what's happening

To view logs:

# View container logs
docker logs mcp-server

Sensitive information in logs is automatically masked.

⁠🧪 Testing Your Setup

You can test that your server is working with simple curl commands:

# Test basic connectivity
curl http://localhost:8080/test

# Check available capabilities
curl http://localhost:8080/capabilities

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

# View OpenAPI specification
curl http://localhost:8080/openapi.yaml

# Run a simple command
curl -X POST http://localhost:8080/tools/runCommand \
  -H "Content-Type: application/json" \
  -d '{"command":"Get-Date"}'

⁠🐳 Alternative Deployment

If you prefer docker-compose:

# Download the compose file
curl -O https://raw.githubusercontent.com/NopeNix/PowerShell-MCP-Server/main/docker-compose.yml

# Start the service
docker-compose up -d

To view logs with docker-compose:

docker-compose logs -f