MCP portman

MCP端口管理器

用于管理计算机上端口注册的模型上下文协议（MCP）服务器。跟踪哪些应用程序正在使用哪些端口，查找空闲端口，并维护端口分配的中央注册表。

特性

• 获取自由港：查找具有操作系统级别验证的可用端口
• 按港口查找：获取有关使用特定端口的信息
• 按应用程序查找：查找已注册到应用程序的所有端口
• 注册端口：向带有描述的应用程序注册端口
• 注销端口：删除端口注册
• JSON持久化：所有注册已保存到 ~/.mcp_portman/registry.json
• 操作系统级别检查：使用套接字绑定验证实际端口可用性

安装

快速安装（Claude代码）

一个直接从GitHub安装的命令：

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

用于全球安装 （适用于您计算机上的所有项目）：

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

验证安装：

claude mcp list

安装范围

根据您的需求选择合适的范围：

• 本地 （默认）：项目/工作区特定，不共享

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

• 用户 （全局）：适用于您计算机上的所有项目

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

• 项目：存储在 .mcp.json 在项目根目录中（可以提交给git进行团队共享）

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

替代方案：Claude桌面手动配置

macOS

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

视窗

编辑 %APPDATA%\Claude\claude_desktop_config.json:

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

编辑后，重新启动Claude Desktop。

地方发展设置

为了当地发展或做出贡献：

# 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

可用工具

1.get_free_port

查找1024-49151范围内的可用端口。

参数：

• preferred_port （可选）：要检查的特定端口

对克劳德的请求示例：

• “给我找个自由港”
• “端口8080可用吗？”
• “为我的web服务器获取可用端口”

退货：

{
  "port": 8080,
  "message": "Port 8080 is available"
}

2.查找_港口

获取特定端口的信息。

参数：

• port：要查找的端口号

对克劳德的请求示例：

• “使用端口3000是什么？”
• “查找端口5432”
• “端口8080注册了吗？”

退货：

{
  "port": 3000,
  "registered": true,
  "app_name": "my-web-app",
  "description": "Development web server",
  "registered_at": "2025-01-15T10:30:00",
  "os_available": false
}

3.查找_应用程序

查找应用程序中注册的所有端口（不区分大小写）。

参数：

• app_name：要搜索的应用程序名称

对克劳德的请求示例：

• “显示postgres的所有端口”
• “我的应用程序正在使用哪些端口？”
• “列出注册到nginx的端口”

退货：

{
  "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.注册端口

向应用程序注册端口。

参数：

• port：要注册的端口号
• app_name：应用程序名称
• description （可选）：端口的用途

对克劳德的请求示例：

• “将端口3000注册到我的web应用程序”
• 为postgres注册端口5432，描述为“主数据库”
• “为nginx开发服务器添加端口8080”

退货：

{
  "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.注销端口

删除端口注册。

参数：

• port：要注销的端口号

对克劳德的请求示例：

• “注销端口3000”
• “从注册表中删除端口8080”
• “删除端口5432的注册”

退货：

{
  "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"
  }
}

端口范围

服务器管理中的端口 用户/注册端口范围：1024-49151

• 0-1023：系统/已知端口（未管理）
• 1024-49151：用户/注册端口（由此服务器管理）
• 49152-65535：动态/专用端口（未管理）

数据存储

端口注册存储在： ~/.mcp_portman/registry.json

目录和文件在首次注册时自动创建。格式：

{
  "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"
  }
}

发展

使用现代Python工具构建：

• FastMCP：构建MCP服务器的现代框架
• 紫外线：快速、可靠的Python包管理器

项目结构

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

在发展中奔跑

# Install dependencies
uv sync

# Run the server
uv run mcp-portman

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

故障排除

服务器未出现在克劳德代码/桌面中

1. 验证安装： claude mcp list 应显示“端口管理器”
2. 检查服务器状态： claude mcp get port-manager
3. 验证是否安装了紫外线： uv --version
4. 对于Claude Desktop：完全重新启动应用程序
5. 检查日志是否有错误

端口显示为不可用但未注册

该端口可能正被其他应用程序使用。服务器检查：

1. 注册表数据库（由MCP端口管理器管理）
2. 操作系统级可用性（实际套接字绑定）

端口必须在两者中都是空闲的，才能被视为可用。

无法写入注册表文件

确保您对主目录具有写入权限。注册表文件创建于 ~/.mcp_portman/registry.json

许可证

MIT许可证-可根据需要自由使用和修改。

贡献

欢迎投稿！请随时提交问题或拉取请求。