🔪 kport - Cross-Platform Port Inspector and Killer
A powerful, cross-platform command-line tool to inspect, kill, and monitor processes using specific ports — with , , , and an for AI agent integration.
Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
A powerful, cross-platform command-line tool to inspect, kill, and monitor processes using specific ports — with , , , and an for AI agent integration.
Fast cross-platform CLI & TUI for port inspection, process termination, Docker awareness, and MCP integration.
kport -I / kport interactive) - Visual TUI with fuzzy search filter, multi-select, and batch kill execution.systemd:unit), PM2 apps (pm2:app), and Supervisord tasks with auto-restart warning/prevention info.--until free|occupied blocks execution until condition met, with --timeout gate.--proto tcp|udp|both.--kill-tree depth-first recursive child process termination.--wait-for-exit <sec> verifies the socket is fully closed/released..kport.json (project, home, or global).--bypass-safety when needed..exe), macOS (.pkg), Debian (.deb), and RPM.Pre-compiled platform-native packages are available on the GitHub Releases page.
# Recommended: Install to user directory
pip install --user kport
# Or install system-wide (requires admin/sudo)
pip install kport
pip install --user git+https://github.com/farman20ali/kport.git
# Clone the repository
git clone https://github.com/farman20ali/kport.git
cd kport
# Install to user directory (recommended)
pip install --user .
python -m kport -h
💡 Tip: If the
kportcommand doesn't work after installation, see TROUBLESHOOTING.md📖 For detailed platform installation options, see docs/INSTALL.md
🛠️ For packaging development and local compilation instructions, see docs/PACKAGING.md
# Inspect a port (local or docker)
kport inspect 8080
# Structured diagnostic analysis (observations, inferences, risks, recommendations)
kport diagnose 8080
# Environment-wide system diagnostics and health report
kport doctor
# Inspect and filter active network connections
kport connections --port 8080
# Explain why a port is blocked
kport explain 8080
# Safely free a port (will offer docker stop/restart/remove if needed)
kport kill 8080
# List ports (local + docker)
kport list
# List docker published ports
kport docker
# Detect port conflicts (docker + local)
kport conflicts
# Reserve/hold a port to block other processes temporarily
kport hold 8080 --timeout 60
# Install system-wide launcher so 'sudo kport' works from pip/pipx installs
kport setup-sudo
# Inspect destructive action history from ~/.kport/audit.log
kport audit --limit 20
Note:
--json,--dry-run,--yes, and--debugwork with all subcommands.
Continuously monitor a port and automatically kill any process that starts using it:
# Watch port 8080 and auto-kill any process that binds to it (check every 1s)
kport watch 8080
# Watch with custom interval (every 2.5 seconds)
kport watch 8080 --interval 2.5
# Watch in dry-run mode (just print alerts, don't kill)
kport watch 8080 --dry-run
# Watch with JSON output (for CI/automation)
kport watch 8080 --json
The Safety Shield prevents accidental termination of critical system services:
# This will be BLOCKED by the Safety Shield (port 22 = SSH):
kport kill 22
# Output: 🛡️ Security Shield Active: Port 22 is a protected port.
# Override the shield when you REALLY need to (use with caution):
kport kill 22 --bypass-safety
# The shield also protects critical processes:
kport kill 8080
# Output if sshd or docker is found: 🛡️ Security Shield: critical process 'docker' ...
Default protected ports: 22 (SSH), 53 (DNS), 80 (HTTP), 443 (HTTPS), 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), 6443 (Kubernetes API)
Default protected processes: systemd, init, docker, dockerd, sshd, explorer.exe, lsass.exe, services.exe
Run kport as an MCP server so AI assistants can inspect and free ports on your behalf:
# Start the MCP server (stdio transport)
kport --mcp
# or
python -m kport.mcp_server
Available MCP tools (21 total):
Read-only / inspection
list_ports — List all active listening ports (local + Docker)inspect_port — Detailed info about a specific portinspect_pid — Inspect a process by PID with port bindings and metadatainspect_process — Inspect all processes matching a name; shows launchers, metadata, and related instancesdiagnose_port — Structured diagnostic analysis (observations, inferences, risks, recommendations)list_connections — Enumerate and filter active network connections (by PID, process, port, state)conflicts — Detect Docker container vs native host process port collisionsdoctor — Environment-wide diagnostics and system health checkfind_project — Resolve a PID's working directory to a Git project contextsuggest_resolution — AI-friendly remediation suggestions for a port conflictfind_alternative_port — Recommend next available free port(s) when EADDRINUSE occursget_audit_history — Inspect audit log history of destructive operationsget_safety_rules — Read the active MCP v2 rule setwatch_ports_snapshot — Capture a one-shot event snapshot from the PortWatcherwatcher_info — Query platform-specific watcher strategy detailsDestructive / write
kill_port — Free a port (always respects the Safety Shield)kill_pid — Terminate a process by PIDkill_process — Terminate all processes matching a namestop_service — Gracefully stop a Windows/systemd/pm2 service managing a portswap — Atomically free a port and hand it over to a new process (zero-race)set_safety_rules — Update the MCP v2 rule set at runtimeConfigure in Claude Desktop / Cursor / VS Code Copilot:
{
"mcpServers": {
"kport": {
"command": "kport",
"args": ["--mcp"]
}
}
}
On Linux, some ports may appear as LISTEN but the owning PID/process name is not visible without elevated privileges (common with system services).
If you see local-unknown in inspect / explain / diagnose, try:
sudo -E kport inspect 6379
sudo -E kport diagnose 6379
If you installed with pip install --user kport, sudo may not find kport because root's PATH doesn't include your user scripts directory.
Alternatives:
# Option 1: keep your PATH when using sudo
sudo -E "$HOME/.local/bin/kport" inspect 6379
# Option 2: run the module via the system python (when working from repo)
sudo -E python3 -m kport inspect 6379
Set persistent defaults via a JSON config file (searched in this priority order):
.kport.json (current directory — project-level)~/.kport.json (user-level)~/.config/kport/config.json (XDG-compliant)Full example config:
{
"yes": true,
"dry_run": false,
"force": false,
"graceful_timeout": 5,
"docker_action": "stop",
"protected_ports": [8080, 9090],
"protected_processes": ["my-critical-app", "postgres"]
}
Note: Setting
protected_portsorprotected_processesin your config extends (is additive to) the default Safety Shield lists.
Find out which process is using a specific port:
kport -i 8080
Example output:
🔍 Inspecting port 8080...
✓ Port 8080 is being used by PID 12345
Process Information:
──────────────────────────────────────────────────
PID: 12345
Image Name: node.exe
Session Name: Console
Mem Usage: 45,678 K
Find all processes matching a name and see what ports they're using:
kport -ip node
Example output:
🔍 Inspecting processes matching 'node'...
Found 3 connection(s) for processes matching 'node':
PID Process Port State
──────────────────────────────────────────────────────────────────────
12345 node.exe 3000 LISTENING
3001 LISTENING
12346 node.exe 8080 LISTENING
✓ Total processes found: 2
✓ Total connections: 3
Check multiple ports at once:
kport -im 3000 3001 8080 8081
Example output:
🔍 Inspecting 4 port(s)...
Port PID Process
────────────────────────────────────────────────────────────
3000 12345 node.exe
3001 12346 node.exe
8080 12347 python.exe
✓ Found processes on 3/4 port(s)
Scan a range of ports:
kport -ir 3000-3010
Example output:
🔍 Inspecting port range 3000-3010 (11 ports)...
Port PID Process
────────────────────────────────────────────────────────────
3000 12345 node.exe
3001 12346 node.exe
3005 12347 python.exe
✓ Found processes on 3/11 port(s) in range
Terminate the process using a specific port:
kport -k 8080
Example output:
🔪 Attempting to kill process on port 8080...
Found PID 12345 using port 8080
Process to be terminated:
PID: 12345
Image Name: node.exe
Are you sure you want to kill this process? (y/N): y
✓ Successfully killed process 12345
Port 8080 is now free.
View all active listening ports and their associated processes:
kport -l
Example output:
📋 Listing all active ports...
Protocol Local Address State PID
──────────────────────────────────────────────────────────────────────
TCP 0.0.0.0:80 LISTENING 1234
TCP 0.0.0.0:443 LISTENING 1234
TCP 0.0.0.0:3000 LISTENING 5678
TCP 0.0.0.0:8080 LISTENING 9012
Kill all processes matching a specific name:
kport -kp node
Example output:
🔪 Killing all processes matching 'node'...
Found 3 process(es) matching 'node':
──────────────────────────────────────────────────
PID 12345: node.exe
PID 12346: node.exe
PID 12347: node.exe
Are you sure you want to kill 3 process(es)? (y/N): y
✓ Killed PID 12345
✓ Killed PID 12346
✓ Killed PID 12347
✓ Successfully killed 3/3 process(es)
Kill processes on multiple ports simultaneously:
kport -ka 3000 3001 3002
Example output:
🔪 Killing processes on 3 port(s)...
Found processes on 3 port(s):
──────────────────────────────────────────────────
Port 3000: PID 12345 (node.exe)
Port 3001: PID 12346 (node.exe)
Port 3002: PID 12347 (python.exe)
Are you sure you want to kill 3 process(es)? (y/N): y
✓ Killed process on port 3000 (PID 12345)
✓ Killed process on port 3001 (PID 12346)
✓ Killed process on port 3002 (PID 12347)
✓ Successfully killed 3/3 process(es)
Ports freed: 3000, 3001, 3002
Kill all processes on a range of ports:
kport -kr 3000-3010
Example output:
🔪 Killing processes on port range 3000-3010 (11 ports)...
Found processes on 3 port(s) in range:
──────────────────────────────────────────────────
Port 3000: PID 12345 (node.exe)
Port 3001: PID 12346 (node.exe)
Port 3005: PID 12347 (python.exe)
Are you sure you want to kill 3 process(es)? (y/N): y
✓ Killed process on port 3000 (PID 12345)
✓ Killed process on port 3001 (PID 12346)
✓ Killed process on port 3005 (PID 12347)
✓ Successfully killed 3/3 process(es)
Ports freed: 3000, 3001, 3005
kport -h
kport -v
netstat, tasklist, taskkilllsof, ss, fuser, ps, killThese tools are typically pre-installed on all platforms.
We provide a unified task runner manage.py at the root of the project to simplify development tasks:
# 1. Clone the repository
git clone https://github.com/farman20ali/kport.git
cd kport
# 2. Set up the development environment (installs package in editable mode and dev dependencies)
python manage.py setup
# Run the test suite (uses pytest, falls back to lightweight runner if not installed)
python manage.py test
Everything is managed via the manage.py entrypoint. To prepare a release:
Update the version number across metadata files:
python manage.py sync-version <version>
Tag a new Git release (which triggers GitHub Actions compilation) and publish packages:
python manage.py publish --release-tag <version>
You can also run python manage.py without arguments to access the interactive menu for all setup, build, publish, test, and release tasks.
See docs/RELEASE_GUIDE.md for detailed manual steps and troubleshooting.
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
What this means:
For questions or commercial inquiries, contact: [email protected]
On Linux/macOS, you may need to run with sudo:
sudo kport -k 80
On Windows, run your terminal as Administrator.
Some processes (especially Java applications) may not respond to graceful termination. Use the --force flag which automatically uses a multi-tier kill strategy (SIGTERM → SIGKILL → fuser):
kport -k 8081 --force
On Linux, kport will automatically use fuser -k as a fallback when standard kill methods fail. This is extremely effective for stubborn Java/Node/Python processes:
# Install fuser for best results (Ubuntu/Debian)
sudo apt-get install psmisc
# Install fuser (RHEL/CentOS/Fedora)
sudo yum install psmisc
# Then kport will automatically use it when needed
kport -k 8081 --force
What happens:
fuser -k 8081/tcp if process still lives (Linux only)Manual alternative: You can also kill a port directly with fuser:
# Kill all processes using port 8081 (requires sudo)
sudo fuser -k 8081/tcp
Make sure the port number is correct and that a process is actually using it. Use kport -l to see all active ports.
Colors should work on Windows 10 and later. If you're on an older version, colors may not display correctly.
Farman Ali Ujjan - [[email protected]]
Project Link: https://github.com/farman20ali/kport
Made with ❤️ for developers who are tired of hunting down processes
kport --helpusage: __main__.py [-h] [--json] [--dry-run] [-y] [--debug] [--config CONFIG]
[--bypass-safety] [-i PORT] [-im PORT [PORT ...]]
[-ir RANGE] [-ip NAME] [-k PORT] [-kp NAME]
[-ka PORT [PORT ...]] [-kr RANGE] [-l] [--exact] [--force]
[--graceful-timeout GRACEFUL_TIMEOUT]
[--wait-for-exit SECONDS] [--kill-tree]
[--proto {tcp,udp,both}] [-I] [-v] [--mcp] [-p PID]
{inspect,explain,stop-service,diagnose,kill,kill-process,list,docker,conflicts,doctor,connections,watch,mcp,interactive,completion,setup-sudo,hold,audit} ...
kport - Cross-platform port inspector and killer
positional arguments:
{inspect,explain,stop-service,diagnose,kill,kill-process,list,docker,conflicts,doctor,connections,watch,mcp,interactive,completion,setup-sudo,hold,audit}
inspect Inspect a port (docker-aware)
explain Explain why a port is blocked
stop-service Cleanly stop the service manager controlling a port
diagnose Structured analysis and fix recommendations for a port
kill Safely free a port (docker-aware)
kill-process Kill processes by name
list List active ports (local + docker)
docker List Docker-published ports
conflicts Detect docker/local port conflicts
doctor Environment-wide read-only diagnostic report
connections List active network connections
watch Live monitoring of port ownership
mcp Start the stdio Model Context Protocol (MCP) server
interactive Launch interactive TUI port picker
completion Generate shell autocompletion scripts
setup-sudo Install a /usr/local/bin/kport launcher so 'sudo
kport' works from pip/pipx installs
hold Temporarily bind and reserve a port to block other
applications
audit Inspect audit log history of destructive kport actions
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
-i, --inspect PORT Inspect specified port
-im, --inspect-multiple PORT [PORT ...]
Inspect multiple ports
-ir, --inspect-range RANGE
Inspect port range
-ip, --inspect-process NAME
Inspect processes by name
-k, --kill PORT Kill processes using port
-kp, --kill-process NAME
Kill processes by name
-ka, --kill-all PORT [PORT ...]
Kill multiple ports
-kr, --kill-range RANGE
Kill processes on range
-l, --list List all listening ports
--exact Exact process name matching
--force Force kill stubborn processes (SIGKILL / fuser)
--graceful-timeout GRACEFUL_TIMEOUT
Seconds to wait before force kill (default: 3.0)
--wait-for-exit SECONDS
Wait for port to be free after killing (up to N
seconds)
--kill-tree Kill the process and all of its descendants
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
-I, --interactive Launch interactive TUI port picker
-v, --version show program's version number and exit
--mcp Start the MCP JSON-RPC server on stdio (alias for
'kport mcp')
-p, --pid PID Specify process ID (PID) for inspection or killing
Examples:
kport -i 8080
kport -im 3000 3001 3002
kport -ir 3000-3010
kport -k 8080 --yes
kport inspect 8080
kport kill 8080 --force
kport mcp
kport inspect --helpusage: __main__.py inspect [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}] [--profile PROFILE]
[-p PID]
[port]
positional arguments:
port
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
--profile PROFILE Named port profile from config
-p, --pid PID Process ID to inspect
kport explain --helpusage: __main__.py explain [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
port
positional arguments:
port
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
kport kill --helpusage: __main__.py kill [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}] [--profile PROFILE]
[--docker-action {stop,restart,rm}] [--force]
[--graceful-timeout GRACEFUL_TIMEOUT]
[--wait-for-exit SECONDS] [--kill-tree] [-p PID]
[port]
positional arguments:
port
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
--profile PROFILE Named port profile from config
--docker-action {stop,restart,rm}
Action when port belongs to Docker
--force
--graceful-timeout GRACEFUL_TIMEOUT
--wait-for-exit SECONDS
Wait for port to be free after killing (up to N
seconds)
--kill-tree Kill the process and all of its descendants
-p, --pid PID Process ID to kill
kport kill-process --helpusage: __main__.py kill-process [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}] [--exact] [--force]
[--graceful-timeout GRACEFUL_TIMEOUT]
[--kill-tree]
name
positional arguments:
name
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
--exact
--force
--graceful-timeout GRACEFUL_TIMEOUT
--kill-tree Kill the process and all of its descendants
kport list --helpusage: __main__.py list [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
kport docker --helpusage: __main__.py docker [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
kport conflicts --helpusage: __main__.py conflicts [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
kport watch --helpusage: __main__.py watch [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}] [--ports PORTS [PORTS ...]]
[--range RANGE] [--interval INTERVAL] [--notify]
[--until {free,occupied}] [--timeout TIMEOUT]
[port]
positional arguments:
port
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
--ports PORTS [PORTS ...]
Multiple ports to watch
--range RANGE Range of ports to watch (e.g. 3000-3010)
--interval INTERVAL Polling interval in seconds
--notify Send OS desktop notification on state change
--until {free,occupied}
Block until port matches state ('free' or 'occupied')
and exit 0
--timeout TIMEOUT Maximum time in seconds to wait when using --until
kport interactive --helpusage: __main__.py interactive [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
kport mcp --helpusage: __main__.py mcp [-h] [--json] [--dry-run] [-y] [--debug]
[--config CONFIG] [--bypass-safety]
[--proto {tcp,udp,both}]
options:
-h, --help show this help message and exit
--json Output machine-readable JSON
--dry-run Show actions without executing
-y, --yes Skip confirmation prompts
--debug Verbose internal logs
--config CONFIG Path to JSON config file
--bypass-safety Bypass safety shields on protected ports/processes
--proto {tcp,udp,both}
Protocol type: tcp, udp, or both (default: tcp)
Fast cross-platform CLI & TUI for port inspection, process termination, Docker awareness, and MCP integration.
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Kport ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-10-28 Fast cross-platform CLI & TUI for port inspection, process termination, Docker awareness, and MCP integration.