MCP Port Manager
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Port Manager Find a free port for my app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Port Manager
A Model Context Protocol (MCP) server for managing port registrations on your computer. Keep track of which applications are using which ports, find free ports, and maintain a central registry of port allocations.
Features
Get Free Port: Find available ports with OS-level verification
Lookup by Port: Get information about what's using a specific port
Lookup by Application: Find all ports registered to an application
Register Port: Register a port to an application with description
Unregister Port: Remove port registrations
JSON Persistence: All registrations saved to
~/.mcp_portman/registry.jsonOS-Level Checking: Verifies actual port availability using socket binding
Related MCP server: Device MCP Server
Installation
There are two implementations of the same server. Both expose the same tools and share ~/.mcp_portman/registry.json.
Version | Idle memory per session | Platforms | Needs |
Rust (recommended) | ~1.3 MB | macOS | Rust toolchain to build |
Python | ~12 MB (+ ~16 MB if launched via | macOS, Linux, Windows |
|
Every Claude Code / Codex session starts its own copy of each MCP server, so per-copy memory adds up with many sessions open.
Rust (macOS)
cargo install --git https://github.com/sooth/mcp_portman mcp-portmanclaude mcp add --scope user port-manager -- ~/.cargo/bin/mcp-portmanCodex (~/.codex/config.toml):
[mcp_servers.port-manager]
command = "/Users/<you>/.cargo/bin/mcp-portman"
args = []Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"port-manager": { "command": "/Users/<you>/.cargo/bin/mcp-portman" }
}
}Python (any platform)
No third-party dependencies; standard library only.
claude mcp add --scope user port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portmanClaude Desktop (macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"port-manager": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sooth/mcp_portman", "mcp-portman"]
}
}
}To skip the uv launcher's memory, install into a venv and point the config at .venv/bin/mcp-portman directly.
Scopes (Claude Code)
Local (default): this project only, not shared
User (
--scope user): all projects on your machineProject (
--scope project): stored in.mcp.jsonin the project root, can be committed
Verify with claude mcp get port-manager. Sessions that are already open keep the command they started with; start a new session to pick up a change.
Available Tools
1. get_free_port
Find an available port in the range 1024-49151.
Parameters:
preferred_port(optional): Specific port to check
Example requests to Claude:
"Find me a free port"
"Is port 8080 available?"
"Get me an available port for my web server"
Returns:
{
"port": 8080,
"message": "Port 8080 is available"
}2. lookup_by_port
Get information about a specific port.
Parameters:
port: Port number to look up
Example requests to Claude:
"What's using port 3000?"
"Look up port 5432"
"Is port 8080 registered?"
Returns:
{
"port": 3000,
"registered": true,
"app_name": "my-web-app",
"description": "Development web server",
"registered_at": "2025-01-15T10:30:00",
"os_available": false
}3. lookup_by_application
Find all ports registered to an application (case-insensitive).
Parameters:
app_name: Application name to search for
Example requests to Claude:
"Show me all ports for postgres"
"What ports is my-app using?"
"List ports registered to nginx"
Returns:
{
"app_name": "postgres",
"count": 2,
"ports": [
{
"port": 5432,
"app_name": "postgres",
"description": "Main database",
"registered_at": "2025-01-15T09:00:00",
"os_available": false
},
{
"port": 5433,
"app_name": "postgres",
"description": "Test database",
"registered_at": "2025-01-15T09:05:00",
"os_available": true
}
]
}4. register_port
Register a port to an application.
Parameters:
port: Port number to registerapp_name: Application namedescription(optional): What the port is used for
Example requests to Claude:
"Register port 3000 to my-web-app"
"Register port 5432 for postgres with description 'Main database'"
"Add port 8080 for nginx development server"
Returns:
{
"success": true,
"message": "Successfully registered port 3000 to \"my-web-app\"",
"port": 3000,
"app_name": "my-web-app",
"description": "Development server",
"os_available": true
}5. unregister_port
Remove a port registration.
Parameters:
port: Port number to unregister
Example requests to Claude:
"Unregister port 3000"
"Remove port 8080 from the registry"
"Delete the registration for port 5432"
Returns:
{
"success": true,
"message": "Successfully unregistered port 3000",
"removed_registration": {
"port": 3000,
"app_name": "my-web-app",
"description": "Development server",
"registered_at": "2025-01-15T10:30:00"
}
}Port Range
The server manages ports in the user/registered port range: 1024-49151
0-1023: System/well-known ports (not managed)
1024-49151: User/registered ports (managed by this server)
49152-65535: Dynamic/private ports (not managed)
Data Storage
Port registrations are stored in: ~/.mcp_portman/registry.json
The directory and file are automatically created on first registration. Format:
{
"3000": {
"app_name": "my-web-app",
"description": "Development server",
"registered_at": "2025-01-15T10:30:00.123456"
},
"5432": {
"app_name": "postgres",
"description": "Main database",
"registered_at": "2025-01-15T09:00:00.654321"
}
}Development
mcp_portman/
├── rust/
│ ├── Cargo.toml
│ └── src/main.rs # Rust server (MCP over stdio, serde_json only)
├── pyproject.toml
└── src/mcp_portman/
└── server.py # Python server (standard library only)Both speak MCP over stdio as newline-delimited JSON-RPC. Keep the two in step when changing a tool.
# Rust: build and install to ~/.cargo/bin
cargo install --path rust
# Python
uv sync
uv run mcp-portmanTroubleshooting
Server not appearing in Claude Code/Desktop
Verify installation:
claude mcp listshould show "port-manager"Check server status:
claude mcp get port-managerCheck the configured command exists (
~/.cargo/bin/mcp-portman, oruv --versionfor the Python version)For Claude Desktop: Restart the application completely
Check logs for errors
Port shows as unavailable but not registered
The port may be in use by another application. The server checks:
Registry database (managed by MCP Port Manager)
OS-level availability (actual socket binding)
A port must be free in BOTH to be considered available.
Cannot write to registry file
Ensure you have write permissions to your home directory. The registry file is created at ~/.mcp_portman/registry.json
License
MIT License - feel free to use and modify as needed.
Contributing
Contributions welcome! Feel free to submit issues or pull requests.
Available Tools
5 toolsget_free_portGet Free PortA
Find and return an available port. Checks both the registry and OS-level availability.
Inputs: preferred_port. Returns: object
lookup_by_applicationLookup By ApplicationA
Find all ports registered to a specific application.
Inputs: app_name (required). Returns: object
lookup_by_portLookup By PortB
Look up information about a specific port.
Inputs: port (required). Returns: object
register_portRegister PortB
Register a port to an application.
Inputs: port (required), app_name (required), description. Returns: object
unregister_portUnregister PortB
Remove a port registration.
Inputs: port (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: finding an available port, looking up by port, looking up by application, registering, and unregistering. There is no meaningful overlap or ambiguity between them.
Tool names generally follow a verb-first pattern, but mix get_, lookup_by_, and register_/unregister_ prefixes. This is still predictable and readable, with only minor stylistic inconsistency.
Five tools is well-scoped for a port management server. Each tool covers an essential operation without unnecessary bloat or redundancy.
The main lifecycle is covered: find a free port, register it, unregister it, and query by port or application. There is no direct update or list-all operation, but these can be worked around via unregister/register or existing lookup tools.
Maintenance
Related MCP Connectors
Publish and discover MCP servers via the official MCP Registry. Powered by HAPI MCP server.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that provides information about installed applications on your computer, support MacOS and Windows.14MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for seamless integration with peripheral devices connected to your computer. Control, monitor, and manage hardware devices through a unified API.5MIT
- FlicenseBqualityDmaintenanceA basic Model Context Protocol (MCP) server implementation that provides a foundation for MCP server development. The README doesn't specify particular functionality, suggesting it may be a template or starting point for building custom MCP servers.1-
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server designed for learning and experimentation. It provides a foundational setup for developers to build, run, and debug MCP server implementations using Node.js.-