mcp-infra

An MCP (Model Context Protocol) server for infrastructure introspection — lets AI assistants query which processes are listening on specific ports on your machine.

What it does

Exposes a single tool to MCP clients (like Claude Desktop or Claude Code):

get_processes_by_ports — given a list of port numbers, returns the process name and PID for each listening socket.

// Example response for ports [8000, 3000]
{
  "8000": [{ "name": "python", "pid": "12345" }],
  "3000": [{ "name": "node", "pid": "67890" }]
}

This is useful when you want your AI assistant to understand what's running on your machine — e.g. "what's listening on port 5432?" or "check if my dev server is up."

Requirements

• Python 3.11+
• Linux (uses ss from iproute2)
• uv (recommended) or pip

Installation

git clone https://github.com/your-username/mcp-infra
cd mcp-infra
uv sync

Or with pip:

pip install -e .

Usage

Run directly

uv run server.py
# or
python server.py

Add to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "infra": {
      "command": "uv",
      "args": ["run", "/path/to/mcp-infra/server.py"]
    }
  }
}

Add to Claude Code

claude mcp add infra -- uv run /path/to/mcp-infra/server.py

Tool reference

get_processes_by_ports(ports: list[int]) -> str

Returns a JSON string mapping each port to a list of processes.

Field	Type	Description
ports	list[int]	Port numbers to query

Response shape per port:

• name — process name
• pid — process ID as string
• raw — unparsed line (fallback if parsing fails)
• error — error message if ss failed for that port

How it works

Uses the ss command (ss -tlnp sport = :<port>) to list TCP sockets in LISTEN state, then parses the users:((...)) field to extract process names and PIDs.

Contributing

Pull requests are welcome. Keep it focused — this is intentionally a small, single-purpose server.

License

MIT