Port desk MCP

Port desk is a local MCP server written in Python. It answers four questions about this machine:

• list_listeners shows TCP and UDP sockets this user can see.

• who_owns names the process on a port and reports whether this process can bind it.

• next_free_port picks a port this process can bind.

• wait_until_free waits until a port can be bound.

The process speaks stdio. It does not open a port of its own except for a bind probe that closes immediately.

The same tools are also available as a Node server in port-desk-mcp. This repository is the Python package, so it can be installed with pip.

Tools

bind.result and wait_until_free.result are free, in_use, forbidden, or error. hidden is true when nothing visible owns the port and the bind probe still finds it taken. next_free_port trusts the bind probe, not lsof.

An empty listeners list means nothing matched. A wait that expires is a normal result with free: false.

Related MCP server: localhost-mcp

Safety

Port desk never signals another process and never reads command lines or environments. list_listeners and who_owns use lsof with a fixed argument list. Port and address filters run after that output is parsed. The bind probe listens on an IP address you pass, then closes the socket before the tool returns. A hostname is rejected so a DNS name cannot choose the address.

Requirements

• Python 3.10 or newer

• lsof on PATH for list_listeners and who_owns

next_free_port and wait_until_free do not need lsof.

Install

From a checkout:

python -m pip install -e ".[dev]"
pytest

The console script is port-desk-mcp. It speaks MCP over stdin and stdout.

After the package is on PyPI:

pip install port-desk-mcp

pipx and uvx work the same way: uvx port-desk-mcp.

Claude

Claude Code can use this checkout after the package is installed into the Python on PATH:

{
  "mcpServers": {
    "port-desk-mcp": {
      "type": "stdio",
      "command": "port-desk-mcp"
    }
  }
}

Claude Desktop uses the same command in claude_desktop_config.json. On macOS that file is ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is %APPDATA%\Claude\claude_desktop_config.json.

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "port-desk-mcp": {
      "command": "port-desk-mcp"
    }
  }
}

Publish to PyPI

The package name on PyPI is port-desk-mcp. From a machine logged in with a PyPI API token:

python -m pip install build twine
python -m build
twine check dist/*
twine upload dist/*

Create the token at https://pypi.org/manage/account/token/. Keep it out of the repository. twine upload asks for the username __token__ and the token as the password.

Example

This is an example of who_owns, not a reading from your machine:

{
  "port": 5901,
  "protocol": "tcp",
  "owners": [
    {
      "protocol": "tcp",
      "address": "127.0.0.1",
      "port": 5901,
      "pid": 2095,
      "process": "Xtigervnc",
      "user": "ubuntu"
    }
  ],
  "bind": { "host": "127.0.0.1", "result": "in_use" },
  "hidden": false
}

Contributing

See CONTRIBUTING.md. The project is licensed under the MIT License.