Porthole
Detects published Docker container ports, labels them by compose project and service, and can stop the specific container instead of killing the host process.
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.
Porthole
Which feature is running on which localhost port, right in your macOS menu bar, labeled by your coding agent.
When you have three checkouts, two worktrees and a Docker stack all serving something on localhost, it's hard to remember that :4100 is your main storefront and :4102 is yesterday's cart-totals fix. Porthole gives every port a name. Your agent (Claude Code, Codex, Cursor or any MCP client) labels the dev server it just started, and the menu shows the label next to the port with its branch, folder and uptime.
Features
Labels from your agent. After starting a dev server, the agent calls
register_server(port, title, description?). Porthole detects the branch and folder itself.Every listening port, labeled or not. Ports in 3000–9999 show up even if nobody labeled them, named by
branch · folder(like:4102above). System processes and database ports are filtered out.One click to open it. Click a row to open it in Chrome (or your browser of choice). Hover it for the details and actions.
Jump to the code. Open the checkout in your editor, a terminal or Finder, at the git root (or the compose project folder for Docker).
Docker-aware. Published container ports are named by compose project · service, and get Stop container… (
docker stopfor just that container) instead of Kill.No port collisions between agents.
suggest_free_porthands out ports that nothing is listening on and no label claims. It reserves them for 2 minutes, so two agents working in parallel never get the same one.Stays current by itself. A server shows up or disappears within ~5 s. If a different checkout takes over a labeled port, the old label is set aside. Labels for ports that stay dead for 24 h are pruned.
Each port's submenu shows the branch, uptime, label age, folder and PID, and these actions:
Open and Copy URL
Open in your editor, terminal or Finder
Rename or Label this port
Remove label
Hide this port
Kill server… (asks first)
Related MCP server: tidyports
Install
Requires macOS, Node 20+ and SwiftBar.
brew install --cask swiftbar # launch it once and pick a plugin folder
git clone https://github.com/GregGlickert/porthole.git && cd porthole
./scripts/install.shinstall.sh is safe to re-run. It installs dependencies, a launcher at ~/.porthole/bin/porthole, and the SwiftBar plugin.
The launcher finds node each time it runs (your nvm default, PATH, Volta or Homebrew), so switching or removing node versions doesn't break the menu or your MCP config. To force a specific node, set PORTHOLE_NODE=/path/to/node.
Connect your agent
Every client runs the same stdio server: ~/.porthole/bin/porthole mcp. Use the full path (install.sh prints it), because most clients don't expand ~.
Claude Code
claude mcp add porthole -s user -- ~/.porthole/bin/porthole mcpCodex
codex mcp add porthole -- ~/.porthole/bin/porthole mcp(or add [mcp_servers.porthole] with command = "/Users/you/.porthole/bin/porthole" and args = ["mcp"] to ~/.codex/config.toml)
Cursor (~/.cursor/mcp.json), Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json), Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"porthole": { "command": "/Users/you/.porthole/bin/porthole", "args": ["mcp"] }
}
}VS Code (.vscode/mcp.json, or the user-level MCP config):
{
"servers": {
"porthole": { "type": "stdio", "command": "/Users/you/.porthole/bin/porthole", "args": ["mcp"] }
}
}The server already tells agents when to use it. For clients that ignore server instructions, add this to your agent rules (~/.claude/CLAUDE.md, AGENTS.md, Cursor rules, …):
When you start a local dev server (or the user says one is running), call the porthole
register_servertool with its port and a ≤8-word title describing the feature/branch being tested. Callsuggest_free_portbefore picking a port. Update or remove the label when that changes.
MCP tools
Tool | What it does |
| Label a running server. Waits up to 10 s for the port to start listening. |
| Change a label. |
| Clear a label (doesn't stop the server). |
| Every listening dev server with its label, branch, folder, uptime and Docker info. |
| Free ports, reserved for 2 minutes. |
CLI
porthole list | register <port> <title> [desc] | remove <port> | open <port> | copy <port> | kill <port>
| confirm-kill <port> | prompt-label <port> | ignore/unignore <port|command> | ignored | edit | swiftbar(Add ~/.porthole/bin to your PATH to get the porthole command, or run node src/cli.js ….)
Settings
Hiding ports
Use Hide this port in a port's submenu, or the CLI:
porthole ignore 8000 # hide a port
porthole ignore claude-science # hide every port owned by a process name
porthole unignore 8000
porthole ignored # show the listHidden items are listed under Settings in the menu. Click one to show it again.
Config file
Settings live in ~/.porthole/config.json. Open it with Settings → Open config file… or porthole edit:
{
"ignorePorts": [8000],
"ignoreCommands": ["claude-science"],
"portMin": 3000,
"portMax": 9999,
"editor": "Zed",
"terminal": "iTerm",
"browser": "Arc"
}editor, terminal and browser are optional:
Editor: without one set, "Open in …" uses the first installed of Cursor, Visual Studio Code, Zed, Windsurf and Sublime Text.
Terminal: without one set, it uses the first installed of Ghostty, iTerm, Warp and Terminal.
Browser: without one set, ports open in Google Chrome if it's installed, otherwise in your default browser.
Environment variables
PORTHOLE_HOME (default ~/.porthole), PORTHOLE_PORT_MIN / PORTHOLE_PORT_MAX (default 3000–9999; portMin / portMax in config.json override these).
How it works
Labels live in
~/.porthole/servers.json. The MCP server, the CLI and the menu all read and write that one file, with atomic writes. There's no daemon to manage.The menu is a SwiftBar streamable plugin: one background process that SwiftBar starts and stops.
Every 5 s it checks the listening ports with
netstat, which takes ~10 ms.Only when that list changes does it run the full scan:
lsoffor each process's folder, plusgit,psanddocker.It watches
~/.porthole/for edits, so label and setting changes show up right away.
Menu clicks go straight to
openandpbcopywhere they can, so opening, copying and "Open in …" don't start node at all.
Tests
npm testLicense
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Deploy local apps, add managed Postgres, and inspect logs from your AI coding agent.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Command center for developers coordinating AI coding agents across projects.
Agent-first hosting: create apps, push code, and deploy to HTTPS URLs from your coding agent.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to discover, configure, and manage local development servers. Provides tools for app registration, port allocation, lifecycle control, and log access without manual config editing.360 npmMIT
- AlicenseNot gradedqualityDmaintenanceSee and control the local dev servers your coding agents leave running. Lists listeners with provenance — which agent, terminal and git worktree started each — kills strays, and allocates collision-free ports so parallel agents stop fighting over :3000.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for managing local dev ports on macOS. It enables AI agents to inspect listening ports, identify owning processes and parent chains, kill processes safely, wait for ports, and report LAN exposure.7 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to deterministically discover which localhost ports and env URLs are actually running, resolving declared configs, OS listeners, and service connections into a machine-readable .portmap.json with actionable findings.1MIT