LM_PS_MCP — LM Studio PowerShell MCP Server

A minimal, environment‑driven MCP server that exposes a persistent PowerShell session to LM Studio. It keeps a single pwsh.exe/powershell.exe process alive and offers tools to run commands, manage cwd, and get/set env vars. Responses to the client are trimmed (default 500 chars) while full I/O is logged.

Features

• Tools: ps_run, cd, cwd, env_get, env_set, ping
• Persistent PowerShell between calls (stateful session)
• 500‑char response trim to the client; full logs on disk
• All paths/config via environment variables (no hardcoded paths)

Install (dev)

cd K:/Repos/LM_PS_MCP
python -m venv .venv
. .venv/Scripts/activate  # Windows
pip install -e .

Run (stdio)

• From WSL (recommended by LM Studio):

bash K:/Repos/LM_PS_MCP/scripts/start_ps_mcp_stdio.sh

• Or directly (Windows):

python -m lm_ps_mcp.server

Environment variables

• LM_PS_MCP_POWERSHELL_PATH — Preferred path to Windows PowerShell 5.1 (default C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe).
• LM_PS_MCP_PWSH — Legacy override for the PowerShell executable (retained for backward compatibility).
• LM_PS_MCP_LOGDIR — log directory (default: <repo>/logs)
• LM_PS_MCP_TRIM_CHARS — max characters returned to client (default: 500)
• LM_PS_MCP_TIMEOUT_SEC — per‑call timeout in seconds (default: 30)
• LM_PS_MCP_MAX_COMMAND_CHARS — maximum PowerShell command length accepted by ps_run (default: 8192)

ps_run tool

• Arguments
  • command (required): exact PowerShell command text passed to -Command.
  • timeout_sec (optional): overrides the per-call timeout (defaults to LM_PS_MCP_TIMEOUT_SEC or 30s).
  • trim_chars (optional): overrides the maximum characters returned to the client (defaults to LM_PS_MCP_TRIM_CHARS or 500).
• Execution
  • Uses Windows PowerShell 5.1 (powershell.exe) with -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass to avoid side effects. Override the path with LM_PS_MCP_POWERSHELL_PATH (or legacy LM_PS_MCP_PWSH).
  • The process runs with the server's current working directory and an environment overlay managed by env_set.
  • The working directory persists across calls; use cd to reposition before running relative-path commands.
• Return payload
  • The tool now returns a JSON object with fields:
    • status: ok, powershell-error, timeout, invalid-command, or internal-error.
    • exit_code: integer PowerShell exit code (or null for tool-level failures).
    • stdout / stderr: decoded (UTF‑16/UTF‑8 aware) output trimmed to trim_chars.
    • message: optional human-readable context (e.g., timeout notice, validation failure).
    • timeout_seconds: populated only for timeout responses so callers know the enforced limit.
• Validation & failure modes
  • Commands must be non-empty strings and shorter than LM_PS_MCP_MAX_COMMAND_CHARS; invalid input returns status: invalid-command without touching PowerShell.
  • Timeouts return status: timeout with any partial decoded output that PowerShell produced.
  • Spawn failures or unexpected exceptions return status: internal-error along with the exception type in message.

LM Studio configuration example

Add to your LM Studio settings JSON:

{
  "mcpServers": {
    "lm_ps_mcp": {
      "command": "bash",
      "args": ["-lc", "K:/Repos/LM_PS_MCP/scripts/start_ps_mcp_stdio.sh"],
      "env": {
        "LM_PS_MCP_PWSH": "/mnt/c/Program Files/PowerShell/7/pwsh.exe",
        "LM_PS_MCP_LOGDIR": "/mnt/k/LMstudio/LM_PS_MCP/logs",
        "LM_PS_MCP_TRIM_CHARS": "500"
      }
    }
  }
}

Smoke test (from LM Studio)

• ps_run → Get-Process | Select-Object -First 3
• cwd → should show current location
• cd → change to a test directory and re‑run cwd
• env_set/env_get → write/read a temp environment variable
• Re‑run ps_run to confirm session persistence

Working directory model

• The MCP server maintains a single-process working directory stored in memory.
• cwd reports the current directory, and cd updates it (accepting absolute or relative paths).
• Subsequent ps_run commands execute within that directory, so Get-ChildItem -Path . and Get-Content on relative paths resolve as expected.
• FastMCP routes requests sequentially, so there is no concurrent mutation of this state; the model matches LM Studio's expectation of a single PowerShell session.

Logs

• Full request/response JSON lines are appended to LM_PS_MCP_LOGDIR/lm_ps_mcp_server.log.

Repo layout

• src/lm_ps_mcp/server.py — MCP server implementation
• scripts/start_ps_mcp_stdio.sh — stdio launcher (used by LM Studio)
• logs/ — default log directory (overridable via LM_PS_MCP_LOGDIR)

License

MIT