Skip to main content
Glama
sooth

MCP Port Manager

by sooth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

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.

Available Tools

5 tools
get_free_portGet Free PortA

Find and return an available port. Checks both the registry and OS-level availability.

ParametersJSON Schema
NameRequiredDescriptionDefault
preferred_portNoOptional specific port to check. If not provided or unavailable, searches for any free port in range 1024-49151.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add a meaningful, non-obvious behavior — the availability check is dual-layered (registry + OS-level) — which earns credit. However, it does not state whether the port is reserved for the caller, whether the check is subject to race conditions, or whether calling this tool has any side effects relative to register_port.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero filler; the purpose verb is front-loaded in the first sentence and the behavioral detail earns its place in the second. This is the appropriate size for a tool with a single optional parameter and an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and an output schema, the description is largely complete: purpose and a key behavioral nuance are covered, and return values are handled by the output schema. The notable gap is the lack of routing context against the sibling tools, which matters because the presence of register_port/unregister_port leaves ambiguity about whether this tool reserves the returned port.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter preferred_port is fully documented by the schema (100% coverage), including the fallback to range 1024-49151 when unavailable, so the baseline of 3 applies. The description's phrase 'checks both the registry and OS-level availability' loosely informs what 'available' means, but adds no syntax or format detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Find and return an available port,' which is unambiguous, and the note about checking 'both the registry and OS-level availability' adds useful scope. However, it does not explicitly differentiate itself from siblings like lookup_by_port or register_port; the distinction is only implicit in the verbs chosen.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage scenario (need an available port) is implied by the purpose statement, but there is no explicit guidance on when to prefer this tool over lookup_by_port, register_port, or unregister_port, and no when-not-to-use conditions. The fallback behavior on preferred_port is documented in the schema, but that is parameter documentation, not usage routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_by_applicationLookup By ApplicationA

Find all ports registered to a specific application.

ParametersJSON Schema
NameRequiredDescriptionDefault
app_nameYesThe application name to search for (case-insensitive).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral disclosure burden. 'Find all ports' clearly signals a non-mutating read and a multi-match result set, which is useful. It does not address empty-result behavior, errors, or permissions, but these are less critical for a simple lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence with no redundant phrases; 'all ports' and 'specific application' are both informative. It is appropriately sized and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, read-only tool with a fully documented input schema and an output schema, the description is largely sufficient. The main omissions are explicit alternative routing and edge-case behavior, which are minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter app_name is already fully described in the input schema, including case-insensitivity. The description adds little semantic value beyond identifying the target concept, so the high schema-coverage baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a concrete verb ('Find') with a specific resource ('all ports registered to a specific application'), so an agent immediately knows this is a query by application name. It also differs from the sibling lookup_by_port, which queries by port number.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is inferable: call this when you have an app_name and need its registered ports. However, the description does not explicitly state when not to use it or name alternatives such as lookup_by_port, so the agent is left to infer routing from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_by_portLookup By PortB

Look up information about a specific port.

ParametersJSON Schema
NameRequiredDescriptionDefault
portYesThe port number to look up.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the burden of behavioral disclosure. It implies a read operation via 'look up' but does not mention potential errors, whether the port must already be registered, or any guarantee about side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no filler or redundant phrasing. The core action and resource are front-loaded and immediately understandable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, has full schema coverage, and has an output schema, so the description covers the basic operation. However, it lacks usage guidance relative to sibling tools and behavioral caveats that would make it fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the port parameter is clearly documented as 'The port number to look up.' The description adds no additional parameter meaning, but the schema already provides sufficient semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb ('look up') and resource ('information about a specific port'), making the core purpose understandable. It distinguishes itself from the register/unregister siblings and from get_free_port, though it does not explicitly contrast with lookup_by_application.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus lookup_by_application or get_free_port. Given the sibling tools, the agent must infer the appropriate lookup scenario without explicit direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

register_portRegister PortB

Register a port to an application.

ParametersJSON Schema
NameRequiredDescriptionDefault
portYesThe port number to register.
app_nameYesThe name of the application using this port.
descriptionNoOptional description of what the port is used for.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Register a port to an application' implies a state-changing operation but does not mention idempotency, whether the port must be free, what happens if the port is already registered, or any permissions needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler or redundant information. It is appropriately sized for a straightforward registration tool and immediately communicates the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and has an output schema plus fully documented parameters, so the basics are covered. However, with no annotations and no mention of behavioral constraints or edge cases, the description is only minimally adequate for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the schema already documents each parameter. The description does not add any additional semantic meaning beyond what the schema provides, matching the baseline for fully documented schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Register') and clearly identifies the resource (a port) and target (an application). It is distinct from the sibling tools like lookup_by_port and unregister_port, though it does not explicitly call out those differences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as get_free_port or unregister_port. The description gives no context about prerequisites, typical scenarios, or situations where another sibling should be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unregister_portUnregister PortB

Remove a port registration.

ParametersJSON Schema
NameRequiredDescriptionDefault
portYesThe port number to unregister.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Remove' signals a mutating operation, but the description does not mention side effects, idempotency, failure behavior, whether the port must already be registered, or what happens to dependent registrations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tight sentence with the action front-loaded and no filler. It is appropriately concise, though it could carry a bit more operational context without becoming bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with an output schema, the core invocation essentials are present: the required port and the action. However, the absence of annotations and any usage or behavioral context leaves an agent to infer edge cases and when to select this tool, so the definition is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the only parameter, port, is clearly described in the schema. The tool description adds no additional parameter semantics, but the baseline score of 3 applies because the schema already carries the full meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Remove') and a specific resource ('a port registration'), making the operation unambiguous. It clearly distinguishes itself from siblings like register_port, lookup_by_port, and get_free_port.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. While the sibling register_port implies the opposite operation, the description does not explicitly state conditions, prerequisites, or when a different tool should be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedget_free_port
    • First observedlookup_by_application
    • First observedlookup_by_port
    • First observedregister_port
    • First observedunregister_port
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Device MCP Server

    akshitsinha
    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

  • Public MCP Server

    Pankhur
    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
    -

  • Learn MCP Server

    saravmani-kmu
    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.
    -