MCP Port Cleaner Server
About
Use this MCP Server when you encounter 'EADDRINUSE' (Address already in use).
Details
- Author
- BrightLin
- Downloads
- 197
- Categories
- Other
Jump to
- Finds and terminates processes occupying specified ports
- Scans and lists all processes on a specified port (cross-platform)
- Safe input validation using Zod schema
- Detailed error handling and response formatting
- Standard MCP protocol compliance for tool registration
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MCP Port Cleaner ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install via npx (npx -y mcp-server-port-cleaner) or globally (npm install -g mcp-server-port-cleaner). Configure it as an MCP server in Claude Desktop or Trae.cn using the tool commands port_scan (list processes on a port) and port_clean (terminate processes on a port), both accepting a port integer (1–65535) as input.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp port cleaner server": {
"port-cleaner": {
"command": "npx",
"args": [
"-y",
"mcp-server-port-cleaner"
]
}
}
}
}McpServers
{
"port-cleaner": {
"command": "npx",
"args": [
"-y",
"mcp-server-port-cleaner"
]
}
}MCP Port Cleaner Server
Node.js server implementing Model Context Protocol (MCP) for port cleanup operations in development environments.
Features
- Finds and terminates processes occupying specified ports
- Scans and lists all processes occupying specified ports (cross-platform support)
- Safe input parameter validation using Zod schema
- Detailed error handling and response formatting
- Standard MCP protocol compliance for tool registration and request processing
Tools
port_scan
Description: Scans and lists all processes occupying a specified port (cross-platform support).
Input Parameters:
{
"port": {
"type": "integer",
"description": "scan process by specify port",
"minimum": 1,
"maximum": 65535
}
}
Response:
- Success: Returns list of processes with details (PID, name, user, protocol)
- Failure: Returns error information
- Port not occupied: Returns appropriate notification
port_clean
Description: Finds and terminates processes occupying a specified port to resolve development environment port conflicts.
Input Parameters:
{
"port": {
"type": "integer",
"description": "clean process by specify port",
"minimum": 1,
"maximum": 65535
}
}
Response:
- Success: Returns list of terminated process IDs
- Failure: Returns error information
- Port not occupied: Returns appropriate notification
Usage Examples
With Claude Desktop or Trae.cn
Docker Configuration
TODO
NPX Configuration
{
"mcpServers": {
"port-cleaner": {
"command": "npx",
"args": [
"-y",
"mcp-server-port-cleaner"
]
}
}
}
or install globally:
npm install -g mcp-server-port-cleaner
and then:
{
"mcpServers": {
"port-cleaner": {
"command": "mcp-server-port-cleaner"
}
}
}
Implementation Details
The server implements the following components:
1. PortCleanerService: Core business logic for port cleanup operations
2. PortScannerService: Cross-platform port scanning functionality
3. MCP Server Integration: Standard MCP protocol implementation with:
- Tool registration (port_clean, port_scan)
- Request handling
- Input validation
4. Error Handling: Comprehensive error handling at both service and server levels
Error Handling
The server provides detailed error responses in all failure scenarios:
- Invalid input parameters
- Process termination failures
- Unexpected runtime errors
Development Notes
- The service uses platform-specific commands:
- Linux/Unix: lsof, kill, netstat
- Windows: netstat, tasklist, taskkill
- Cross-platform compatibility implemented with process detection
- The cleanup implementation terminates processes with SIGKILL (-9)
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
