English | 简体中文

Port Viewer

Port Viewer is a local TCP / UDP port and process inspection tool. It provides both a desktop UI and an MCP interface:

• Desktop app: built with pywebview + Vue 3, with visual pages for port queries, process queries, process details, process trees, and process termination.

• MCP server: built with FastMCP, exposing port and process operations as MCP tools for clients such as Codex, Claude Code, and Cursor.

This project is mainly designed for local Windows usage. Because it can terminate processes and process trees, only deploy it in trusted environments.

Features

The desktop app provides:

• Query IPv4 / IPv6 and TCP / UDP port usage.

• Query a specific port, a port range, or ports occupied by one or more PIDs.

• Filter occupied and free ports.

• View the process list for an occupied port.

• View all processes occupying TCP / UDP ports.

• View process details, occupied ports, and process trees.

• Terminate a process or a process tree.

• Simplified Chinese, Traditional Chinese, and English UI.

The MCP server provides:

• List TCP / UDP / IPv4 / IPv6 network connections.

• Query a specific port, endpoint, listening port, or established connection.

• Check whether a port is in use.

• Query all ports occupied by a process.

• Query all processes using a port.

• Find any free port or all free ports in a specified range.

• Terminate a process.

• Return the process tree containing a specified process.

• Terminate the process tree containing a specified process.

Related MCP server: OPNsense MCP

Project Structure

portviewer/
  netstatmanager.py      # Core port and process management logic
  mcpmain.py             # MCP stdio entry point
  webviewmain.py         # pywebview desktop backend entry point
  frontend/              # Vue 3 + Vite frontend project
  frontpage/             # Built frontend files loaded by the desktop app
  pyproject.toml         # Python project configuration
  uv.lock                # Python dependency lock file

Requirements

• Windows

• Python 3.11 or later

• uv, recommended for Python dependency installation

• Node.js and npm, only needed when rebuilding the frontend

Python dependencies include:

• fastmcp

• psutil

• pywebview

Install Dependencies

Run this in the project root:

cd H:\portviewer
uv sync

If you are not using uv, create a virtual environment manually:

cd H:\portviewer
python -m venv .venv
.venv\Scripts\python.exe -m pip install fastmcp psutil pywebview

Run the Desktop App

The desktop entry point is webviewmain.py.

cd H:\portviewer
.venv\Scripts\python.exe webviewmain.py

The desktop app loads frontpage/index.html. If you modify the Vue code under frontend, rebuild the frontend first:

cd H:\portviewer\frontend
npm install
npm run build
cd ..
.venv\Scripts\python.exe webviewmain.py

Run the MCP Server

The MCP entry point is mcpmain.py. It uses stdio transport by default.

cd H:\portviewer
.venv\Scripts\python.exe mcpmain.py

When started normally, the stdio MCP server waits for an MCP client to communicate over standard input and standard output. It does not open a window and does not provide an interactive command-line UI. Press Ctrl+C to exit during manual testing.

Local stdio Deployment Recommendation

During development, you can use the project directory directly:

H:\portviewer

For a more stable local deployment, copy the project to a fixed directory such as:

C:\Tools\portviewer-mcp

Then install dependencies there:

cd C:\Tools\portviewer-mcp
uv sync

The MCP configuration examples below use the development directory H:\portviewer. If you deploy to C:\Tools\portviewer-mcp, replace the paths accordingly.

Configure MCP in Codex

Codex stores MCP configuration in config.toml. The user-level configuration file is usually:

C:\Users\<your-user-name>\.codex\config.toml

You can also use a project-level configuration:

H:\portviewer\.codex\config.toml

Steps

1. Make sure dependencies are installed:

cd H:\portviewer
uv sync

2. Open or create the Codex configuration file:

notepad $env:USERPROFILE\.codex\config.toml

If the .codex directory does not exist, create it first:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad $env:USERPROFILE\.codex\config.toml

3. Add the complete configuration:

[mcp_servers.portviewer]
command = "H:\\portviewer\\.venv\\Scripts\\python.exe"
args = ["H:\\portviewer\\mcpmain.py"]
cwd = "H:\\portviewer"
startup_timeout_sec = 15
tool_timeout_sec = 120

4. Restart Codex.

5. In Codex, run:

/mcp

Confirm that portviewer is connected.

Configure MCP in Claude Code

Claude Code can add a stdio MCP server from the command line or from a JSON configuration.

Method 1: Add with Command Line

Run this in PowerShell:

claude mcp add --transport stdio portviewer -- H:\portviewer\.venv\Scripts\python.exe H:\portviewer\mcpmain.py

Then inspect the server:

claude mcp get portviewer

Inside a Claude Code session, you can also run:

/mcp

to check the MCP connection status.

Method 2: Use JSON Configuration

Create .mcp.json in the project root, or use Claude Code's user-level configuration. Example project-level .mcp.json:

{
  "mcpServers": {
    "portviewer": {
      "type": "stdio",
      "command": "H:\\portviewer\\.venv\\Scripts\\python.exe",
      "args": [
        "H:\\portviewer\\mcpmain.py"
      ],
      "env": {}
    }
  }
}

Restart Claude Code after saving, then use /mcp to verify the connection.

Configure MCP in Cursor

Cursor uses mcp.json to configure MCP servers. You can use a project-level or global configuration.

Project-level configuration:

H:\portviewer\.cursor\mcp.json

Global configuration:

C:\Users\<your-user-name>\.cursor\mcp.json

Project-level configuration is useful when you only want this MCP server in the current project. Global configuration makes it available in all Cursor workspaces.

Steps

1. Create the project-level configuration directory:

cd H:\portviewer
New-Item -ItemType Directory -Force .cursor
notepad .cursor\mcp.json

2. Write the complete configuration:

{
  "mcpServers": {
    "portviewer": {
      "type": "stdio",
      "command": "H:\\portviewer\\.venv\\Scripts\\python.exe",
      "args": [
        "H:\\portviewer\\mcpmain.py"
      ],
      "env": {}
    }
  }
}

3. Restart Cursor.

4. Confirm that portviewer is enabled in Cursor's MCP settings or Agent MCP list.

Cursor also supports global configuration. Create or edit:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.cursor"
notepad "$env:USERPROFILE\.cursor\mcp.json"

Use the same JSON configuration.

MCP Usage Examples

After the server is connected, ask your MCP client things like:

List all currently listening TCP ports.

Find free ports between 3000 and 9000.

Show all ports used by PID 1234.

Show the process tree containing PID 1234.

Terminate the process with PID 1234.

Security Notes

Port Viewer MCP can read local network connection and process information, and it can terminate processes and process trees. Keep these points in mind:

• Enable it only in trusted local environments.

• Do not expose this MCP server to the public internet.

• If you convert it to a long-running HTTP service, bind to 127.0.0.1 by default.

• For process termination tools, verify the target PID and executable path before calling them.

References

• MCP Transport Specification: https://modelcontextprotocol.io/specification/draft/basic/transports

• Codex MCP Configuration: https://codex-console.com/config

• Claude Code MCP Documentation: https://code.claude.com/docs/en/mcp

• Cursor MCP Documentation: https://prod.cursor.com/docs/mcp