systeminternals-mcp (scaffold)

Minimal FastMCP-compatible scaffold that demonstrates dynamic registration and safe subprocess wrapping for exposing Sysinternals and NirSoft binaries.

Quick demo:

python server.py --demo procexp64

Start the MCP stdio server:

python server_mcp.py

Edit config.ini to adjust server settings (log level, timeout, allow_destructive). The server no longer requires explicit binary paths — it scans the binaries/ directory recursively.

Security notes: This scaffold sanitizes arguments and uses asyncio.create_subprocess_exec without a shell. Extend with explicit safety filters before using in production.

Safety filter: destructive tools (for example sdelete, psexec, pskill) are blocked by default. To run them you must either:

• Add --confirm to the tool arguments, or
• Set allow_destructive = true in the [server] section of config.ini.

The server also scans a binaries directory recursively if present; place your tool folders (e.g., systeminternals, nirsoft) under binaries.

Setup

Prerequisites:

• Python 3.11+ (recommended) and venv.

Quick setup:

python -m venv .venv
.\.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

Running

• Run a single-tool demo (CLI):

python server.py --demo pslist64

• Start the long-running MCP stdio server (for agent integration):

python server_mcp.py

The --demo mode is useful for simple CLI usage and for coding agents that can execute shell commands and parse JSON output. server_mcp.py exposes the full MCP stdio endpoint for clients that implement the MCP protocol.

Using from a CLI or a coding agent

1. Simple CLI / scripting approach (recommended for automation and agents that can run subprocesses): the --demo command prints JSON to stdout which is easy to parse from any language.

Example Python snippet (agent or script):

import subprocess, json

proc = subprocess.run([
	'python', 'server.py', '--demo', 'pslist64', '--',
	# additional tool args go here as separate items
], capture_output=True, text=True)

if proc.returncode == 0 and proc.stdout:
	result = json.loads(proc.stdout)
	print(result)
else:
	print('error', proc.stderr)

Note: place any tool arguments after --demo <toolname>; the demo command will join remaining argv pieces for the tool.

2. Long-running MCP server (for advanced agents):

• Start the server with python server_mcp.py (it will register tools from binaries.json or the binaries/ directory).
• Use an MCP-capable client to connect over stdio (spawn the server as a child process and implement the MCP framing). Many agent frameworks support providing a long-lived process that the agent can call into; in that case the MCP stdio server gives a stable RPC surface.

If your agent framework doesn't implement MCP natively, use the simple subprocess approach above to execute server.py --demo per-request.

Security and best practices

• Never allow untrusted agents or users to run destructive tools. Destructive tools are blocked by default; confirmations are required (interactive prompt, --confirm or allow_destructive=true in config.ini).
• When generating per-tool schemas or probing help text, run the probe in an isolated environment (VM or disposable container) to avoid accidental execution of unsafe binaries.
• For production use, add authentication around the MCP stdio process and run under restricted privileges.

CI

A GitHub Actions workflow is included at .github/workflows/ci.yml that runs the test suite on push and pull requests.

mcpServers (IDE / agent integration)

If your editor/agent supports a mcpServers config (for example the Gemini client settings), add entries that either start the stdio MCP server or point to a running HTTP MCP endpoint.

Example — start the long-lived stdio MCP server from this repo (preferred for full MCP integration):

"systeminternals-mcp": {
	"command": "python",
	"args": [
		"C:\\path\\to\\the\\server_mcp.py"
	]
}

Example — demo/one-shot entry that runs --demo and prints JSON (useful for simple agents that call subprocesses):

"systeminternals-mcp-demo": {
	"command": "python",
	"args": [
		"C:\\path\\to\\the\\server.py",
		"--demo"
	]
}

Example — point to an existing HTTP MCP endpoint:

"systeminternals-mcp-http": {
	"url": "http://127.0.0.1:12345/mcp"
}

Notes:

• Use absolute Windows paths (escape backslashes in JSON) or a plain python command if the environment activates the virtualenv automatically.
• If your client supports cwd and env, set them so the server runs in the repo root and uses the .venv Python.
• Prefer the stdio MCP server (server_mcp.py) for integrated agents; use --demo for simple per-request subprocess calls that return JSON.