lmstudio-terminal-mcp

MCP server that gives LM Studio (and any other MCP host) bash / PowerShell access on the local machine, with structured outputs, background-process support, and opt-in unattended hardening.

Note on name: PyPI's terminal-mcp is owned by an unrelated project. This package is published as lmstudio-terminal-mcp.

Install for LM Studio (chat UI)

Option A — one-click deeplink

Generate a deeplink button and open it in any browser:

python scripts/gen_deeplink.py --name terminal

Click the resulting lmstudio://add_mcp?... link. LM Studio will prompt for confirmation.

Option B — paste into mcp.json

1. LM Studio → Program tab → Install → Edit mcp.json
2. Add:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["lmstudio-terminal-mcp"],
      "env": {
        "TERMINAL_MCP_DEFAULT_CWD": "C:/Users/YOU/Documents",
        "TERMINAL_MCP_MAX_TIMEOUT_SEC": "600"
      }
    }
  }
}

3. Save. LM Studio hot-reloads.

Prerequisites

• uv on PATH (winget install astral-sh.uv on Windows)
• Python 3.11+

Tools

Unattended / API use

Read before enabling. The cwd allowlist restricts the initial working directory only — it is not a filesystem sandbox. A child shell can still read or write any absolute path the server's OS user can access, open outbound network connections, and exfiltrate data. For real isolation layer a container, Windows Sandbox, firejail, or a separate VM around this server.

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["lmstudio-terminal-mcp"],
      "env": {
        "TERMINAL_MCP_UNATTENDED": "1",
        "TERMINAL_MCP_CWD_ALLOWLIST": "C:/Users/YOU/projects",
        "TERMINAL_MCP_COMMAND_ALLOWLIST": "git\\s+(status|log|diff|branch)(\\s+[\\w\\-./=: ]*)?,npm\\s+(install|run\\s+\\w+|test)(\\s+[\\w\\-./=: ]*)?"
      }
    }
  }
}

Unattended mode will refuse to start without TERMINAL_MCP_CWD_ALLOWLIST, and without either TERMINAL_MCP_COMMAND_ALLOWLIST or TERMINAL_MCP_UNATTENDED_ACK_NO_ALLOWLIST=1.

Configuration reference

Development

git clone https://github.com/knowlesindustry/lmstudio-terminal-mcp
cd lmstudio-terminal-mcp
uv pip install -e ".[dev]"
pytest

Dev install into LM Studio:

{
  "mcpServers": {
    "terminal": {
      "command": "python",
      "args": ["-m", "lmstudio_terminal_mcp"]
    }
  }
}

License

MIT — see LICENSE.