Skip to main content
Glama

PortMaster MCP

by smspgh
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

PortMaster MCP

PowerShell Python Windows

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables comprehensive Windows process and service management with secure UAC elevation. Supports discovery, inspection, and control of processes by name, PID, or port number, with both AI-assisted and direct command-line interfaces.

  1. Overview
    1. ๐Ÿš€ Dual Interface Design
  2. Key Features
    1. ๐Ÿ” Discovery & Inspection
    2. ๐Ÿ› ๏ธ Management Capabilities
    3. ๐Ÿ”’ Security Features
  3. Installation
    1. Prerequisites
    2. Quick Setup (Recommended)
    3. 1. Install Python Dependencies
    4. 2. Configure PowerShell Execution Policy
    5. 3. Add to Claude Code Settings
    6. 4. Restart Claude Code
  4. Standalone CLI Usage
    1. ๐Ÿš€ Quick Start
    2. Option 1: Automated Setup (Recommended)
    3. Option 2: Quick CLI Examples
    4. ๐Ÿ“‹ CLI Commands Reference
  5. Claude Code Usage Examples
    1. Service Management
    2. Port-Based Discovery
    3. Process Management
    4. Multiple Process Analysis
    5. Advanced Operations
  6. Available MCP Tools
    1. Discovery Tools (No Admin Required)
    2. Management Tools (UAC Elevation Required)
  7. File Structure
    1. How UAC Elevation Works
      1. Troubleshooting
        1. Getting Service Names
        2. Checking Port Usage
      2. Security Considerations
        1. Safe Operations
        2. Admin Operations
        3. Best Practices
      3. Example Workflows
        1. Troubleshooting a Web Service
        2. Cleaning Up Development Processes
        3. Managing Database Services
        4. Analyzing Multiple Processes (NEW)
      4. ๐Ÿ”ง Advanced Configuration
        1. PowerShell Execution Policy
        2. Custom Port Ranges
        3. Environment Variables
      5. ๐Ÿค Contributing
        1. Development Setup
      6. ๐Ÿ“„ License
        1. ๐Ÿ™ Acknowledgments

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/smspgh/portmaster_mcp'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server