PortMaster MCP

Overview

PortMaster MCP is a comprehensive Windows process and service management tool that provides both AI-assisted and direct command-line interfaces. It enables secure discovery, inspection, and control of any Windows service or process by name, PID, or port number with integrated UAC elevation.

🚀 Dual Interface Design

• 🤖 Claude Code Integration: Full MCP server for AI-assisted process management
• ⚡ Standalone CLI: Direct PowerShell interface via portmaster-cli.ps1
• 🔒 Unified Security: Consistent UAC elevation across both interfaces

Key Features

🔍 Discovery & Inspection

• Find processes by service name (supports wildcards)
• Find processes listening on specific ports or port ranges
• Get detailed process information by single or multiple PIDs
• List all listening ports on the system
• Analyze complete process trees with parent/child relationships
• Network connection analysis (listening ports + active connections)
• Process chain visualization with memory and resource usage

🛠️ Management Capabilities

• Kill individual processes by PID
• Kill multiple processes at once
• Kill all processes using specific ports
• Start, stop, and restart Windows services
• UAC elevation for admin operations (no need to run Claude Code as admin)

🔒 Security Features

• UAC Elevation: Only prompts for admin privileges when needed
• Confirmation Required: All destructive operations require explicit confirmation
• Safe Defaults: Read-only operations work without elevation
• Process Tree Analysis: Shows impact before performing operations

Installation

Prerequisites

• Windows OS (Windows 10/11 or Windows Server)
• Python 3.8+
• PowerShell (pre-installed on Windows)
• Claude Code installed

Quick Setup (Recommended)

Option A: Automatic Setup

# Install dependencies and configure automatically
pip install -r requirements.txt
python portmaster_mcp_setup.py

The setup script will:

• ✅ Check dependencies and PowerShell policy
• ✅ Automatically add MCP server to your Claude config
• ✅ Create backup of existing config
• ✅ Show next steps

Option B: Manual Setup

1. Install Python Dependencies

pip install -r requirements.txt

2. Configure PowerShell Execution Policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Add to Claude Code Settings

Add this configuration to your Claude Code settings file (%USERPROFILE%\.claude.json):

{
  "mcpServers": {
    "portmaster_mcp": {
      "type": "stdio",
      "command": "python",
      "args": [
        "C:\\path\\to\\your\\portmaster_mcp\\portmaster_mcp.py"
      ],
      "env": {}
    }
  }
}

Replace the path with your actual installation directory.

4. Restart Claude Code

Close and restart Claude Code to load the new MCP server.

Standalone CLI Usage

For direct command-line access without Claude Code, use the included portmaster-cli.ps1 script:

🚀 Quick Start

Option 1: Automated Setup (Recommended)

# Clone and setup in one go
git clone <repository-url> portmaster_mcp
cd portmaster_mcp
pip install -r requirements.txt
python portmaster_mcp_setup.py

Option 2: Quick CLI Examples

# Check what's running on development ports
.\portmaster-cli.ps1 check-ports 3000-3005

# Check specific ports
.\portmaster-cli.ps1 check-ports 443,8080,8443

# Find services with wildcards
.\portmaster-cli.ps1 find-service "*Docker*"

# Get detailed process info with full chain analysis
.\portmaster-cli.ps1 process-info 1234

# Kill processes on specific ports (requires admin)
.\portmaster-cli.ps1 kill-port 8080 -Force

# Show all available commands
.\portmaster-cli.ps1 help

📋 CLI Commands Reference

Command	Description	Admin Required	Example
check-ports <ports>	Check what's listening on ports	❌	check-ports 3000-3005
all-ports	Show all listening ports	❌	all-ports
find-service <pattern>	Find services by pattern	❌	find-service "*Docker*"
service-info <name>	Get service details	❌	service-info "W3SVC"
process-info <PID>	Comprehensive process analysis	❌	process-info 1234
kill-process <PID>	Terminate specific process	✅	kill-process 1234
kill-port <ports>	Kill processes using ports	✅	kill-port 8080 -Force
kill-multiple <PIDs>	Kill multiple processes	✅	kill-multiple 1234,5678
stop-service <name>	Stop Windows service	✅	stop-service "Docker"
start-service <name>	Start Windows service	✅	start-service "W3SVC"
restart-service <name>	Restart Windows service	✅	restart-service "IIS"

Claude Code Usage Examples

Service Management

"Find processes for services matching SQL*"
"Find processes for WindowsTestService" 
"Find processes for *Web*"
"Stop service W3SVC"
"Start service MSSQLSERVER"
"Restart service Docker Desktop Service"

Port-Based Discovery

"What process is listening on port 80?"
"Find processes on ports 443, 8080, and 3000"
"Kill all processes using port 8080"

Process Management

"Get detailed information about process 1234"
"Get information about multiple processes 1234, 5678, 9012"
"Kill process 5678"
"Kill processes 1234, 5678, 9012"
"Show me all listening ports"

Multiple Process Analysis

"Analyze processes 51008 and 30200 together"
"Compare resource usage for PIDs 1234, 5678, 9012"
"Show network connections for processes 51008, 30200"
"Get detailed chain info for multiple Node.js processes"

Advanced Operations

"Find all IIS-related services and their ports"
"Stop all Node.js processes on development ports"
"Find which service is using port 443 and restart it"

Available MCP Tools

Discovery Tools (No Admin Required)

Tool	Description	Example Usage
find_processes_by_service	Find processes for any service pattern	"Find *SQL* services"
find_processes_by_port	Find processes on specific ports	"What's on port 80?"
get_all_listening_ports	List all listening ports	"Show all ports"
get_process_info	Get details for a PID	"Info for process 1234"
get_multiple_process_info	NEW: Get details for multiple PIDs	"Info for processes [1234, 5678]"
get_service_info	Get details for a service	"Info for W3SVC service"

Management Tools (UAC Elevation Required)

Tool	Description	Security
kill_process	Terminate a process by PID	UAC + Confirmation
kill_processes_by_port	Kill all processes on port(s)	UAC + Confirmation
kill_multiple_processes	Kill multiple processes by PIDs	UAC + Confirmation
stop_service	Stop a Windows service	UAC + Confirmation
start_service	Start a Windows service	UAC
restart_service	Restart a Windows service	UAC + Confirmation

File Structure

portmaster_mcp/
├── portmaster_mcp.py        # Main MCP server with UAC elevation
├── portmaster-cli.ps1       # Standalone CLI interface
├── admin_helper.ps1         # PowerShell helper for elevated operations
├── portmaster_mcp_setup.py  # Automatic setup script
├── requirements.txt         # Python dependencies
└── README.md               # This documentation

How UAC Elevation Works

1. Normal Operations: Claude Code runs with standard user privileges
2. Admin Required: When you request a destructive operation (kill process, stop service)
3. UAC Prompt: Windows shows a UAC dialog asking for administrator approval
4. Elevated Execution: If approved, the operation runs with admin privileges in a separate session
5. Return to Normal: After completion, returns to standard privileges

This approach is more secure than running Claude Code as administrator constantly.

Troubleshooting

"Administrator privileges required"

• This is normal for kill/service operations
• Approve the UAC prompt when it appears
• If UAC is disabled, you could run Claude Code as Administrator but I would advise to NOT do this.

"PowerShell execution policy error"

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

"Module not found" errors

pip install mcp pydantic

"Service not found"

• Use wildcards: *partial-name*
• Check exact service name: Get-Service in PowerShell

"Process not found"

• Process may have already terminated
• Check PID with Task Manager or Get-Process

Getting Service Names

To find the exact names of Windows services:

Get-Service | Where-Object {$_.DisplayName -like "*keyword*"}

Checking Port Usage

To see what's using ports:

netstat -ano | findstr :PORT_NUMBER

Security Considerations

Safe Operations

• Read operations never require elevation
• Discovery tools are completely safe
• UAC prompts appear only for destructive operations

Admin Operations

• Always confirm before approving UAC prompts
• Review the operation in the confirmation dialog
• Cancel if you're unsure about the operation

Best Practices

• Use discovery tools first to understand what you're managing
• Review process trees before killing multiple processes
• Prefer service operations over direct process killing when possible
• Test on non-critical systems first

Example Workflows

Troubleshooting a Web Service

1. "Find processes for *Web*" - Discover web-related services
2. "What's listening on port 80?" - Check if port is in use
3. "Get info for service W3SVC" - Get IIS service details
4. "Restart service W3SVC" - Restart if needed

Cleaning Up Development Processes

1. "Find processes on ports 3000, 8080, 9000" - Find dev servers
2. "Kill processes using ports 3000, 8080" - Clean up dev ports
3. "Show all listening ports" - Verify cleanup

CLI Alternative:

.\portmaster-cli.ps1 check-ports 3000-9000
.\portmaster-cli.ps1 kill-port 3000,8080 -Force
.\portmaster-cli.ps1 all-ports

Managing Database Services

1. "Find services matching *SQL*" - Find database services
2. "Stop service MSSQLSERVER" - Stop SQL Server
3. "Start service MSSQLSERVER" - Start SQL Server

Analyzing Multiple Processes (NEW)

Comprehensive analysis of multiple processes at once:

Claude Code Examples:

"Analyze processes 51008 and 30200 together"
"Compare memory usage for Node.js processes 1234, 5678"
"Show network connections for multiple processes [51008, 30200]"

CLI Example:

# Get detailed info on multiple processes
.\portmaster-cli.ps1 process-info 51008  # Individual analysis
.\portmaster-cli.ps1 process-info 30200  # Individual analysis

What Multiple Process Analysis Shows:

• Individual Details: Complete process info for each PID
• Parent/Child Relationships: Process tree visualization
• Network Analysis: Listening ports + active connections per process
• Resource Summary: Combined memory usage and process type grouping
• Process Chain: How processes relate to each other
• Service Associations: Which processes belong to services

Example Output Summary:

Found: 2 of 2 processes
Total Memory: 113.7 MB
Process Types:
  node: 2 instances

🔧 Advanced Configuration

PowerShell Execution Policy

If you encounter execution policy errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Custom Port Ranges

The CLI supports flexible port specifications:

# Single ports
.\portmaster-cli.ps1 check-ports 80

# Multiple ports
.\portmaster-cli.ps1 check-ports 80,443,8080

# Port ranges
.\portmaster-cli.ps1 check-ports 3000-3010

# Mixed notation
.\portmaster-cli.ps1 check-ports 80,443,3000-3005,8080

Environment Variables

Set these for customized behavior:

• PORTMASTER_TIMEOUT - Command timeout in seconds (default: 30)
• PORTMASTER_FORCE_COLOR - Force colored output (true/false)

🤝 Contributing

PortMaster MCP is designed with these principles:

• 🛡️ Security First - UAC elevation only when needed
• 🔧 Extensible - Easy to add new commands and features
• 🎯 User-Friendly - Clear confirmations and error messages
• 📊 Comprehensive - Complete process and service lifecycle management

Development Setup

git clone <repository-url>
cd portmaster_mcp
pip install -r requirements.txt

# Test CLI
.\portmaster-cli.ps1 help

# Test MCP server
python portmaster_mcp.py

📄 License

This project is provided as-is under the MIT License for managing Windows processes and services.

🙏 Acknowledgments

• Built for Claude Code MCP integration
• Powered by Windows PowerShell and Python
• Designed for Windows system administrators and developers