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

Installation

Quick Install (Claude Code)

One command to install directly from GitHub:

claude mcp add port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portman

For global installation (available in all projects on your machine):

claude mcp add --scope user port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portman

Verify installation:

claude mcp list

Installation Scopes

Choose the appropriate scope for your needs:

• Local (default): Project/workspace-specific, not shared

  claude mcp add port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portman
  

• User (global): Available across all projects on your machine

  claude mcp add --scope user port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portman
  

• Project: Stored in .mcp.json in project root (can be committed to git for team sharing)

  claude mcp add --scope project port-manager -- uvx --from git+https://github.com/sooth/mcp_portman mcp-portman
  

Alternative: Claude Desktop Manual Configuration

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "port-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sooth/mcp_portman",
        "mcp-portman"
      ]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "port-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sooth/mcp_portman",
        "mcp-portman"
      ]
    }
  }
}

After editing, restart Claude Desktop.

Local Development Setup

For local development or contributing:

# Clone the repository
git clone https://github.com/sooth/mcp_portman.git
cd mcp_portman

# Install dependencies
uv sync

# Run the server
uv run mcp-portman

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

Built with modern Python tools:

• FastMCP: Modern framework for building MCP servers
• uv: Fast, reliable Python package manager

Project Structure

mcp_portman/
├── pyproject.toml              # Project configuration
├── README.md                   # This file
├── .gitignore                  # Git ignore rules
└── src/
    └── mcp_portman/
        ├── __init__.py         # Package initialization
        └── server.py           # Main MCP server implementation

Running in Development

# Install dependencies
uv sync

# Run the server
uv run mcp-portman

# Or run directly with Python
uv run python -m mcp_portman.server

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. Verify uv is installed: uv --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.