Skip to main content
Glama

portgraph

ci npm JSR JSR Score Rust license

One line: npx portgraph (or bunx portgraph): live local port topology (Docker + Ollama/LM Studio/vLLM) as a terminal TUI and stdio MCP server.

Install

Bun / npm:

bunx portgraph
npx portgraph

# or install in your project / globally
bun add -d portgraph
npm i -D portgraph

JSR:

bunx jsr add @kanchingyg/portgraph
npx jsr add @kanchingyg/portgraph

Cargo (Rust native binary):

cargo install --git https://github.com/kanchingyg/portgraph

The scan engine and MCP stdio server are written in Rust (src/lib.rs, src/main.rs, src/mcp.rs). TypeScript under src/*.ts is included for npx / bunx / JSR usage and MCP bridge helpers when no native binary is present.

Related MCP server: portviewer

CLI

npx portgraph
bunx portgraph
npx portgraph who :3000
npx portgraph kill :3000 --allow-write
npx portgraph --mcp
npx portgraph --mcp --allow-write
npx portgraph --mcp --dry-run   # blocks mutating tools only

MCP Tools Reference

Tool

Mutates

Description

get_local_topology

false

List active TCP listening ports, owning PIDs, Docker container port mappings, and local LLM server tags (Ollama, LM Studio, vLLM).

who_owns_port

false

Return the process ID, executable name, and command line bound to a specific TCP port.

kill_port_owner

true

Terminate the process listening on a port when confirm: true is passed (requires --allow-write; blocked under --dry-run).

Editor and Agent Integration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "portgraph": {
      "command": "npx",
      "args": ["-y", "portgraph", "--mcp"]
    }
  }
}

Claude Code CLI

claude mcp add portgraph -- npx -y portgraph --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/portgraph/bridge";

Runtime Safety and Guardrails

  • Stdio frame isolation: When --mcp is active, hijackStdoutForMcp() redirects accidental console.log calls to stderr so JSON-RPC 2.0 frames on stdout never corrupt.

  • Read-only by default: Mutating tools (mutates: true) are blocked in --dry-run mode and require explicit --allow-write authorization.

  • Loop breaker: Repeated identical (toolName, args) invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.

  • Context budget truncation: Tool outputs are middle-truncated (60% head / 40% tail) scaled to the probed local model n_ctx (Ollama /api/show, llama.cpp /props, vLLM /v1/models).

  • Secret redaction and path normalization: AWS keys (AKIA*, ASIA*), bearer tokens, and sk-* keys are scrubbed before returning tool output, and Windows drive paths (C:\...) translate cleanly to /mnt/c/... when WSL mode is enabled.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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 npm
      1
      MIT
    • F
      license
      C
      quality
      B
      maintenance
      Enables local TCP/UDP port and process inspection via MCP tools, including querying connections, checking port usage, listing processes, and terminating processes or process trees.
      30
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables users to inspect local TCP and UDP listening sockets, identify which process owns a given port and whether it can be bound, find a port available to bind, and wait until a busy port frees up. Queries run through stdio without reading command lines, environments, or signaling other processes.
      MIT