os-control-mcp

Local MCP for persistent terminal sessions. The process keeps Bash, CMD, PowerShell, pwsh, or WSL active and separates input sending from incremental output reading.

It also has persistent goals: the agent can create a goal with acceptance criteria, run multiple steps, verify evidence, and continue until it completes, fails, gets blocked, or reaches the defined limits.

Warning: this server controls processes with the permissions of the user who runs it. Use it locally, do not run as administrator/root by default, and never expose the process directly to the internet.

Transport

The server uses MCP JSONL over stdio. It does not open a network port by default.

Related MCP server: Persistent Terminal MCP Server

Shells

• bash, sh, zsh on POSIX systems;

• cmd, powershell, and pwsh on Windows;

• wsl-bash on Windows, using the distribution defined in OS_CONTROL_WSL_DISTRO or kali-linux by default.

Interactive flow

1. os_create_session creates a persistent session.

2. os_send_input writes immediately to the PTY/ConPTY.

3. os_read_output uses since_seq to fetch only new output.

4. os_session_status tracks PID, shell, directory, and termination.

Outside of an autonomous goal, potentially destructive commands require explicit confirmation. In an autonomous goal, authorization is continuous within the step and time limits defined by the goal. The server is intended for local use and should remain protected by authentication and scoping when placed behind a remote tunnel.

Autonomous goals

Recommended flow:

1. os_create_session creates the persistent terminal.

2. os_goal_start receives the goal, criteria, and session_id.

3. os_send_input uses the goal_id to run without repetitive confirmation.

4. os_read_output reads the incremental output.

5. os_goal_update records action, result, evidence, and next step.

6. The agent repeats until all criteria are proven.

The server does not invent the next action or call the model on its own; it maintains the state and limits of the goal. The client/agent must keep making calls until the terminal state.

Installation

git clone https://github.com/Willian-2-0-0-1/os-control-mcp.git
cd os-control-mcp
python -m pip install -r requirements.txt

On Windows, pywinpty enables ConPTY for CMD and PowerShell. On Kali/Linux, the backend uses the native PTY. The .mcp.json file can be used by MCP clients that accept local servers over stdio.

Plugin for GPT/Codex

The repository contains the .codex-plugin/plugin.json manifest and the MCP server. This allows distributing the package to clients compatible with MCP plugins.

To use with ChatGPT with a local server, each user must run their own instance and configure a private connection. A GitHub repository, by itself, does not give ChatGPT access to the user's computer.