Skip to main content
Glama
MCP Port Manager
by sooth

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

  • OS-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 uv/uvx)

macOS, Linux, Windows

uv

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-portman
claude mcp add --scope user port-manager -- ~/.cargo/bin/mcp-portman

Codex (~/.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-portman

Claude 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 machine

  • Project (--scope project): stored in .mcp.json in 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 register

  • app_name: Application name

  • description (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-portman

Troubleshooting

Server not appearing in Claude Code/Desktop

  1. Verify installation: claude mcp list should show "port-manager"

  2. Check server status: claude mcp get port-manager

  3. Check the configured command exists (~/.cargo/bin/mcp-portman, or uv --version for the Python version)

  4. For Claude Desktop: Restart the application completely

  5. Check logs for errors

Port shows as unavailable but not registered

The port may be in use by another application. The server checks:

  1. Registry database (managed by MCP Port Manager)

  2. 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 tools
get_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

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Five tools is well-scoped for a port management server. Each tool covers an essential operation without unnecessary bloat or redundancy.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      5
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -