This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Build an MCP server that answers "what is using port 3000?" and frees it safely, from raw sockets up. No wrappers hiding how it works, every line explained, every module run for real.
At the end you will have built a small version of ports-mcp yourself, and you will understand the parts most MCP tutorials skip: how to let a model trigger something destructive without letting it hurt you, and how to test a process-killing tool against real processes instead of mocks.
Most MCP tutorials stop at a weather API. The hard part of a useful server is elsewhere:
asking the operating system the right question, and being honest when it refuses to answer
not trusting what you just read (a PID can be reused; a process can respawn)
designing a destructive tool so a confused model costs one extra message, not a lost database
behaving the same on Windows, macOS and Linux, or saying clearly where it cannot
tests that start real listeners on random ports and check the real port afterwards
Related MCP server: mcp-infra
Developers who built a "hello world" MCP server and want to build a real one
Anyone who has typed netstat -ano | findstr :3000 or lsof -i :3000 one time too many
Anyone designing tools that give an AI agent power over a machine
Prerequisites: Python 3.10+ and basic familiarity with sockets. Then
pip install -r requirements.txt. No QEMU, no admin rights, no containers. Node is not needed.
# | Module | What You'll Build |
01 | What bind/listen really do, why | |
02 | Port to PID to command line to working directory, and treating AccessDenied as information | |
03 | Descendants, ancestors, PID reuse, and a supervisor that undoes your kill | |
04 | Plan then confirm, single-use expiring port-bound tokens, hard refusals, terminate then kill, verify | |
05 | A stdio MCP server, agent-readable errors ( | |
06 | Visibility by privilege, | |
07 | Real listener fixtures, ground-truth assertions, injectable time, and what one machine cannot prove |
Each module contains:
README.md: the concepts and design decisions
main.py: a working, commented implementation that asserts its own claims
break-it.md: challenges that break your own code, with hints
Each main.py stands alone: no imports between modules. Module 05 repeats Module 04's kill
core verbatim, and verify.py checks the two copies never drift.
pip install -r requirements.txt
python 04-safety-and-confirm-tokens/main.py # any single module
python verify.py # every module, plus the drift checkverify.py exits non-zero if any module's assertions fail.
Everything here was run on Windows 11 (Python 3.12). The Linux and macOS behavior described in
Module 06 comes from documentation and is encoded as assertions, but has not been run on those
systems by the author. Run python verify.py on your platform; where it disagrees with the text,
the code is right and the text needs a fix.
AI agent (Claude Desktop, Claude Code, ...)
| MCP over stdio: JSON-RPC tool calls <- Module 05
v
+----------------------------------------------------+
| tools: whats_on_port, kill_port(plan|confirm), ... | <- Module 05
| +-- safety: plan, tokens, refusals, verify | <- Module 04
| +-- trees: children, parents, identity | <- Module 03
| +-- psutil: sockets -> pids -> process details | <- Module 02
+----------------------------------------------------+
| the operating system's socket table <- Module 01, 06MIT
This server cannot be deployed
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Runtime permission, approval, and audit layer for AI agent tool execution.
Trust signals for AI agents: an open agent-readiness standard and developer tool guide. Read-only.
