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.22+ (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.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | filter | string | no | Case-insensitive substring match on process 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.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pid | number | yes | Process ID to kill |

{ "pid": 1234 }

Response:

Killed process 1234

find_process_by_port

Find which process is using a specific TCP port. Returns PID, process name, protocol, and connection state.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | port | number | yes | TCP port number to look up |

{ "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

kill_process_by_port

Kill the process using a specific TCP port. Single-step: finds the process and kills it.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | port | number | yes | TCP port number — kill the process using this port |

{ "port": 3000 }

Response:

Killed pid:1234 name:node.exe (was on port 3000)

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

Architecture

• main.go — Entry point, CLI subcommand dispatch
• server/ — MCP server setup, tool registration (stdio transport)
• tools/ — MCP tool handlers (process listing/killing, port lookup)
• 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