port-manager-mcp

Port management MCP server. Check, find, and kill processes by port number.

No shell. No curl. No cross-platform escaping hell.

Install

npm install -g port-manager-mcp

Usage

Claude Desktop / Cursor / OpenCode

Add to your MCP config:

{
  "mcpServers": {
    "port-manager": {
      "command": "npx",
      "args": ["-y", "port-manager-mcp"]
    }
  }
}

Tools

check_port — Check Port Status

Check if a port is available or in use. Returns process info if occupied.

Input:

{
  "port": 3000,
  "host": "127.0.0.1"
}

Output (free):

{
  "port": 3000,
  "host": "127.0.0.1",
  "status": "free"
}

Output (in use):

{
  "port": 3000,
  "host": "127.0.0.1",
  "status": "in_use",
  "process": {
    "pid": 12345,
    "name": "node.exe",
    "command": "node server.js"
  }
}

find_free_port — Find Available Ports

Find available ports in a given range.

Input:

{
  "start": 3000,
  "end": 3010,
  "count": 3
}

Output:

{
  "requested": 3,
  "found": 3,
  "ports": [3000, 3001, 3002],
  "range": { "start": 3000, "end": 3010 }
}

kill_process — Kill Process by Port

Kill the process occupying a specific port.

Input:

{
  "port": 3000,
  "force": true
}

Output:

{
  "success": true,
  "killed_pid": 12345,
  "killed_name": "node.exe",
  "port": 3000,
  "message": "Successfully killed process 12345 (node.exe) on port 3000"
}

Design

| Feature | Why | |---------|-----| | Cross-platform | Windows (netstat/taskkill), macOS/Linux (lsof/kill) | | Zero runtime deps | Only @modelcontextprotocol/sdk and zod | | Structured output | AI reads status/pid/name precisely | | Safe kill | Verifies port is freed after killing |

License

MIT