English | [简体中文](README-zh.md)

# 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.

## Project Structure

```text
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:

```powershell
cd H:\portviewer
uv sync
```

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

```powershell
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`.

```powershell
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:

```powershell
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.

```powershell
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:

```text
H:\portviewer
```

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

```text
C:\Tools\portviewer-mcp
```

Then install dependencies there:

```powershell
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:

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

You can also use a project-level configuration:

```text
H:\portviewer\.codex\config.toml
```

### Steps

1. Make sure dependencies are installed:

```powershell
cd H:\portviewer
uv sync
```

2. Open or create the Codex configuration file:

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

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

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

3. Add the complete configuration:

```toml
[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:

```text
/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:

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

Then inspect the server:

```powershell
claude mcp get portviewer
```

Inside a Claude Code session, you can also run:

```text
/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`:

```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:

```text
H:\portviewer\.cursor\mcp.json
```

Global configuration:

```text
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:

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

2. Write the complete configuration:

```json
{
  "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:

```powershell
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:

```text
List all currently listening TCP ports.
```

```text
Find free ports between 3000 and 9000.
```

```text
Show all ports used by PID 1234.
```

```text
Show the process tree containing PID 1234.
```

```text
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