win-taskman-mcp

win-taskman-mcp

A lightweight MCP (Model Context Protocol) server that provides AI agents with Windows process and port management tools. No more fragile tasklist | findstr or netstat -ano pipelines — just structured, cross-shell tools that work reliably.

Why?

AI agents frequently need to manage processes during development — killing a stuck dev server, finding what's blocking a port, or listing running services. Doing this via Bash on Windows is fragile: tasklist output parsing breaks, netstat needs piping through findstr, and PowerShell commands have quoting issues. This MCP server provides clean, structured tools that work identically regardless of shell.

Requirements

• Windows 10 or later (uses Win32 APIs available since Windows 10)
• Go 1.25+ (build from source only)

Quick Start

Download binary

Pre-built binaries are available on the Releases page.

Build from source

git clone https://github.com/lexandro/win-taskman-mcp.git
cd win-taskman-mcp
go build -trimpath -ldflags="-s -w" -o win-taskman-mcp.exe .

Register in Claude Code

The register subcommand automatically adds the server to Claude Code's config — no manual JSON editing needed.

# Register for a project (creates .mcp.json in the project root)
./win-taskman-mcp.exe register project /path/to/your/project

# Or register globally for all projects (updates ~/.claude.json)
./win-taskman-mcp.exe register user

That's it — Claude Code will automatically discover and use the process management tools.

Manual configuration

You can also edit the config files directly:

{
  "mcpServers": {
    "win-taskman-mcp": {
      "command": "C:\\path\\to\\win-taskman-mcp.exe"
    }
  }
}

MCP Tools

list_processes

List running Windows processes. Optionally filter by name.

{ "filter": "node" }

Response:

pid:1234 name:node.exe ppid:5678
pid:2345 name:node.exe ppid:5678

Results are capped at 100 entries. Use filter to narrow down.

kill_process

Kill a Windows process by PID. With tree: true the whole process tree dies — on Windows, TerminateProcess does not kill children, so a dev server's orphaned workers would otherwise keep holding the port.

{ "pid": 1234, "tree": true }

Response:

Killed process tree of 1234 (3 processes)
pid:1234 name:cmd.exe
pid:5678 name:node.exe
pid:9012 name:esbuild.exe

get_process_info

Get details for one process: name, parent PID, threads, memory usage, executable path, and command line. The command line tells apart multiple processes with the same name (e.g. several node.exe). Uses ProcessCommandLineInformation (Windows 8.1+) — no process memory reading needed.

{ "pid": 1234 }

Response:

pid:1234 name:node.exe ppid:880 threads:14 working_set_mb:120.3 private_mb:98.1
path:C:\Program Files\nodejs\node.exe
cmdline:"C:\Program Files\nodejs\node.exe" server.js --port 3000

Fields that cannot be read (protected system processes) show (unavailable).

find_process_by_port

Find which process is using a TCP or UDP port. Scans both IPv4 and IPv6 tables — dev servers that bind only [::] (common with Node.js/Bun on Windows) are found too. Returns PID, process name, protocol, and connection state.

{ "port": 3000 }

Response:

pid:1234 name:node.exe port:3000 proto:TCP state:LISTEN local:0.0.0.0 remote:0.0.0.0:0
pid:1234 name:node.exe port:3000 proto:TCP state:LISTEN local:::

UDP rows have no state or remote address (connectionless):

pid:5678 name:dnsmasq.exe port:5353 proto:UDP local:0.0.0.0

kill_process_by_port

Kill the process using a TCP or UDP port (IPv4 and IPv6). Single-step: finds the process and kills it. With tree: true each port owner's child processes die too.

{ "port": 3000, "tree": true }

Response:

Killed pid:1234 name:node.exe (was on port 3000)
Killed pid:5678 name:esbuild.exe (tree child)

Token Efficiency

All output is designed to minimize context window usage:

• Compact key:value format — pid:1234 name:node.exe instead of verbose tables
• No decorative chrome — no box drawing, banners, or redundant headers
• Bounded results — max 100 processes, truncation reported
• Errors as text — Error: access denied not a stack trace
• Tool annotations — list_processes, get_process_info, and find_process_by_port declare readOnlyHint, so MCP clients like Claude Code can run them without a permission prompt; kill tools declare destructiveHint

Architecture

• main.go — Entry point, CLI subcommand dispatch
• server/ — MCP server setup, tool registration (stdio transport)
• tools/ — MCP tool handlers (process listing/killing/info, port lookup/killing)
• taskman/ — Windows task management core (Win32 API calls via golang.org/x/sys/windows)
• register/ — register subcommand for Claude Code config auto-registration

Communication

• Stdio-only MCP transport (no HTTP, no open ports)
• Logs to stderr, never to stdout
• All output AI-optimized: compact key:value format, no decorative chrome

Development

# Build
go build -trimpath -ldflags="-s -w" -o win-taskman-mcp.exe .

# Test
go test ./...

# Vet
go vet ./...

License

MIT