portview

io.github.MapikaPublished by GitHub account Mapikav2.1.0Updated Oct 25, 2026

See what's on your ports, the processes behind them, and diagnose conflicts and leaks.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

A local MCP server that lets an assistant list listening ports, inspect the processes behind them, diagnose conflicts, and terminate processes.

What you can do
List listening ports with process details such as PID, user, command, memory and uptime, and find ports by process name or command substring. Inspect a single port, including working directories, child processes and open connections. Run diagnostics for port conflicts, wildcard exposure, connection buildup and high memory use. Compare current ports against a baseline to see what opened, closed or changed owner. Terminate the process using a port, with a dry-run preview option.
When to use it
Useful when an assistant is debugging local development servers: finding what occupies a port, spotting leaked or conflicting listeners, or freeing a stuck port. Best for developers working on their own machine rather than shared or production hosts.
Requirements
Runs as a local process over stdio; the MCP server is built into the portview binary, which is installed via Homebrew, an install script, cargo, or a release binary. No accounts, API keys or environment variables are declared. Docker-related checks need the docker CLI and daemon; SSH features use the system ssh client.
Before you install
The kill_port tool terminates processes and is marked destructive; run with the read-only flag to disable it. Killing the wrong process can stop services or lose unsaved work. On Linux, naming other users' processes needs sudo, and on macOS other users' ports are not listed without it. Docker and SSH modes act on containers and remote hosts.

Installation

In SourceWeft

  1. Open portview in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

portview

[CI] [Crates.io] [License: MIT]

portview lists ports and the processes using them on Linux, macOS, and Windows. It shows process names, commands, memory usage, and uptime. You can inspect a port, stop its process, or monitor changes in an interactive terminal UI.

[portview demo]

It also supports Docker, remote hosts over SSH, and an MCP server for coding agents.

Install

Homebrew:

bash
brew install mapika/tap/portview

Linux / macOS:

bash
curl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh

Windows (PowerShell):

powershell
irm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex

Or use cargo install portview, or download a binary from Releases.

What it does

bash
portview                          # list all listening portsportview 3000                     # inspect port 3000 in detailportview node                     # find ports by process nameportview watch                    # interactive TUI with live refreshportview watch --docker           # TUI with Docker containers as rowsportview kill 3000 --force        # terminate the process using port 3000portview doctor                   # diagnose port conflicts and issuesportview ssh user@server          # inspect ports on a remote hostportview ssh user@server watch    # remote TUI over SSHportview ssh user@server --agentless   # no portview needed on the remoteportview mcp                      # run as an MCP server for AI agents

Features

Scan

$ portview╭──────┬───────┬─────┬──────────────┬──────┬────────────┬────────┬────────┬────────────────────────────╮│ PORT │ PROTO │ PID │ ADDR         │ USER │ PROCESS    │ UPTIME │ MEM    │ COMMAND                    │├──────┼───────┼─────┼──────────────┼──────┼────────────┼────────┼────────┼────────────────────────────┤│ 3000 │ TCP   │ 8   │ 127.0.0.1    │ root │ node       │     7s │  44 MB │ node /opt/app/web.js       ││ 5000 │ TCP   │ 11  │ 127.0.0.1    │ root │ python3.12 │     7s │  18 MB │ python3 /opt/app/worker.py ││ 6380 │ TCP   │ 12  │ 127.0.0.1    │ root │ node       │     7s │ 1.2 GB │ node /opt/app/cache.js     ││ 7000 │ TCP   │ 10  │ 127.0.0.1    │ root │ node       │     7s │  45 MB │ node /opt/app/ingest.js    ││ 8080 │ TCP   │ 9   │ 127.0.0.1    │ root │ node       │     7s │  44 MB │ node /opt/app/api.js       │╰──────┴───────┴─────┴──────────────┴──────┴────────────┴────────┴────────┴────────────────────────────╯

--all includes non-listening connections, with one row per connection. --wide shows full commands. --json produces JSON output for scripts.

Ports whose owner can't be resolved are still listed, with - in the columns that can't be filled. That happens for another user's process without sudo, and for sockets like TIME_WAIT that outlive the process that opened them.

The scan, doctor, and MCP examples below are real output, captured by demo/record.sh inside an isolated namespace — which is why the user is root and the paths are /opt/app. The Docker example is illustrative, since it needs a running daemon.

MCP server (for AI agents)

portview mcp provides port queries, diagnostics, and process termination over the Model Context Protocol using stdio. To register it with Claude Code:

bash
claude mcp add portview -- portview mcp

Or configure it manually:

json
{  "mcpServers": {    "portview": {      "command": "portview",      "args": ["mcp"]    }  }}
ToolWhat it does
list_portsList listening ports with available process details
inspect_portInspect a port, including process working directories and descendants
find_processFind ports by process name or command substring
doctorCheck for conflicts, wildcard exposure, connection buildup, and high memory usage
diff_portsReport ports that opened, closed, or changed owner since a baseline
kill_portTerminate processes using a port; dry_run previews the targets. Marked destructive to the client

[portview MCP server demo]

The MCP server is included in the portview binary. Pass --read-only to disable the kill_port tool:

bash
portview mcp --read-only

Listed in the MCP Registry as mcp-name: io.github.Mapika/portview.

Watch mode (interactive TUI)

bash
portview watch                    # live-refresh every 1sportview watch --docker           # include Docker containersportview watch --sort mem         # sort by memory on launch
KeyAction
j/k, ↑/↓Navigate rows
EnterInspect port (full command, cwd, children, connections)
d/DKill process or manage Docker container
/Filter across all columns
←/→, rCycle sort column, reverse direction
tToggle process tree view
aToggle all/listening-only
qQuit

Tree view (t): Groups child processes under their parents.

Detail view (Enter): Shows the full unwrapped command, working directory, child process list with ports, and open connections (in --all mode).

Doctor

portview doctor checks for port conflicts, wildcard bindings, connection buildup, and high memory usage:

$ portview doctor  ✓ No port conflicts  ✓ No wildcard exposure issues  ! Port 7000 has 16 CLOSE_WAIT connections — possible connection leak  ! node (PID 12) is listening on port 6380 and using 1.2 GB of memory
  2 warnings found
CheckFlags
Port conflictsMultiple PIDs bound to the same port
Wildcard exposureDatabases (postgres, redis, mysql, mongod, …) listening on 0.0.0.0
Docker-host conflictsA container publishing a port the host already uses
Connection buildupHigh counts of TIME_WAIT or CLOSE_WAIT connections on one port; these do not by themselves establish a leak
High memory usageListening processes using more than 1 GB of resident memory

Docker is auto-detected. portview doctor --json for scripting (exit code 1 on errors).

In CI

The GitHub Action runs doctor and can fail a workflow on errors or warnings:

yaml
- uses: mapika/portview@v2  with:    fail-on: error        # error | warning | never

It annotates each finding inline on the run, writes a summary table, and exposes findings (JSON), count, errors, and warnings as step outputs:

yaml
- uses: mapika/portview@v2  id: doctor  with:    fail-on: never- run: echo '${{ steps.doctor.outputs.findings }}' | jq .

Set install: false if portview is already on PATH. Linux and macOS runners.

SSH remote mode

Inspect ports on a remote host over SSH:

bash
portview ssh user@server              # one-shot scanportview ssh user@server watch        # full interactive TUIportview ssh user@server doctor       # remote diagnosticsportview ssh user@server 3000         # inspect a remote portportview ssh user@server --ssh-opt "-p 2222"  # custom SSH port

Kill actions in the remote TUI are forwarded over SSH.

If portview is not installed on the remote host, SSH mode collects data using ss and ps, or lsof and ps where ss is unavailable. This requires a POSIX shell and the collection tools on the remote host.

$ portview ssh user@serverportview not found on user@server — falling back to agentless mode (ss + ps over SSH).╭──────┬───────┬─────┬──────────────┬──────┬─────────┬────────┬───────┬──────────────────────╮│ PORT │ PROTO │ PID │ ADDR         │ USER │ PROCESS │ UPTIME │ MEM   │ COMMAND              │├──────┼───────┼─────┼──────────────┼──────┼─────────┼────────┼───────┼──────────────────────┤│ 3000 │ TCP   │ 6   │ 127.0.0.1    │ root │ node    │     3s │ 45 MB │ node /opt/app/web.js ││ 8080 │ TCP   │ 7   │ 127.0.0.1    │ root │ node    │     3s │ 45 MB │ node /opt/app/api.js │╰──────┴───────┴─────┴──────────────┴──────┴─────────┴────────┴───────┴──────────────────────╯

Use --agentless to collect data this way even when portview is installed on the remote host. It supports scans, port inspection, process search, diagnostics, and watch mode.

Run diagnostics on the collected data:

bash
portview ssh user@server doctor --agentless

This uses the same diagnostic checks as local mode. The Docker check is skipped because agentless mode does not query remote containers.

Watch remote ports, with process termination available in the TUI:

bash
portview ssh user@server watch --agentless

Watch mode collects updates through a single persistent SSH connection.

Docker integration

Use --docker to include ports published by Docker containers:

$ portview --docker╭──────┬───────┬───────┬──────────────┬────────┬──────────┬────────┬────────┬────────────────────────────╮│ PORT │ PROTO │ PID   │ ADDR         │ USER   │ PROCESS  │ UPTIME │ MEM    │ COMMAND                    │├──────┼───────┼───────┼──────────────┼────────┼──────────┼────────┼────────┼────────────────────────────┤│ 3000 │ TCP   │ 48291 │ 127.0.0.1    │ mark   │ node     │ 3h 12m │ 248 MB │ next dev [docker:web]      ││ 8080 │ TCP   │ -     │ 0.0.0.0      │ docker │ pv-nginx │      - │      - │ nginx:alpine :8080->80/tcp │╰──────┴───────┴───────┴──────────────┴────────┴──────────┴────────┴────────┴────────────────────────────╯

Container-only rows have no host process, so PID, UPTIME, and MEM render as -.

In watch mode, press d on a Docker row to stop or restart the container, or follow its logs.

JSON output

bash
portview --json                   # pipe to jq, scripts, dashboardsportview --docker --json          # includes Docker ownership dataportview watch --json             # streaming JSON, one array per tickportview doctor --json            # machine-readable diagnostics

Custom colors

bash
PORTVIEW_COLORS="port=red,pid=magenta,command=bright_cyan" portview

Columns: port, proto, pid, user, process, uptime, mem, command. Use --no-color to disable.

How it works

Local port and process data comes from OS interfaces:

FieldLinuxmacOSWindows
Ports/proc/net/tcp{,6}, udp{,6}proc_pidfdinfoGetExtendedTcp/UdpTable
PIDinode→pid via /proc/*/fd/proc_listpidsIncluded in socket table
Process/proc/<pid>/exeproc_pidpathQueryFullProcessImageNameW
Memory/proc/<pid>/status VmRSSproc_pidinfoK32GetProcessMemoryInfo
Uptime/proc/<pid>/statproc_pidinfoGetProcessTimes

On Linux, portview reads the executable name from /proc/<pid>/exe. The thread name in /proc/<pid>/comm can be changed by the runtime and is limited to 15 bytes.

Docker integration uses the docker CLI. SSH mode uses the system ssh client to run portview or the agentless collection tools on the remote host. MCP mode uses newline-delimited JSON-RPC 2.0 on stdin/stdout.

Building from source

bash
git clone https://github.com/mapika/portviewcd portviewcargo build --release

Requires Rust 1.85+ (edition 2024). Shell completions and man page are generated at build time.

The repository includes a Dockerfile. To inspect the host from a container, share the host's network and PID namespaces:

bash
docker run --rm -i --network host --pid host portview

Contributing

See CONTRIBUTING.md for development setup and guidelines, and demo/README.md for regenerating the recordings.

Changes should type-check on all three platforms, not just yours:

bash
cargo check --target aarch64-apple-darwincargo check --target x86_64-pc-windows-msvc

Limitations

  • Linux: Other users' ports are listed, but naming the process needs sudo (it reads /proc/<pid>/fd/). Rows you can't attribute show - for PID, user, process, and command rather than being hidden.
  • macOS: Other users' ports are not listed without sudo — sockets are enumerated per process via proc_pidfdinfo, so a process that can't be opened contributes nothing to enumerate. For the same reason doctor cannot detect TIME_WAIT pileups there; CLOSE_WAIT is detected normally.
  • Windows: Ports owned by inaccessible system processes are listed with the PID but - for name and user. Kill always force-terminates. Run as Administrator for full detail.
  • Docker: Requires docker CLI and daemon access
  • SSH: every command falls back to agentless collection when portview is missing on the remote, using ss + ps on Linux and lsof where ss does not exist. The remote needs one of those and a POSIX shell. Agentless collection cannot see Docker on the far end, so that check reports as skipped rather than passed.

License

MIT

Source: README.md at commit 63052cd

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts