port-finder

Tiny HTTP service that tells you the next available host port in the 27000-27999 range, based on what's actually assigned on the Docker host it runs on (via the Docker socket).

Endpoints

• GET / - plain text next free port, e.g. 27002
• GET /?format=json - {"port": 27002, "range": [27000, 27999]}
• GET /?port=27050 - plain text true/false, whether that specific port is free
• GET /?port=27050&format=json - {"port": 27050, "available": true}
• GET /?count=5 - plain text comma-separated list of the next 5 free ports, e.g. 27002,27004,27005,27006,27007
• GET /?count=5&format=json - {"ports": [...], "count": 5, "requested": 5, "range": [27000, 27999]}
• GET /used - JSON array of every port currently assigned to a container
• GET /health - ok

port and count are mutually exclusive with each other (and with the default single-port behavior) - if both are given, port wins.

How it decides "used"

On each request it lists all containers on the host (running or stopped) and collects every HostPort in HostConfig.PortBindings. Any port in 27000-27999 not in that set is "available"; it returns the lowest one. ?port= checks are not limited to that range.

Because it checks live container config rather than keeping its own registry, removing a container frees its port automatically - no manual release step.

MCP server

mcp_server.py exposes the same functionality as MCP tools over SSE, so Claude (or any MCP client) can query it directly:

• get_next_available_port()
• get_next_available_ports(count)
• check_port_available(port)
• list_used_ports()