Persistent Shell

You run a persistent shell MCP server that powers AI-assisted command execution across isolated workspaces. It uses tmux to keep shells alive, supports interactive processes, and provides clean user-facing output separate from raw shell data. This lets you orchestrate commands, long-running tasks, and development workflows with reliability and isolation.

How to use

Set up a workspace for your project, then use the provided MCP client to run commands in two dedicated windows. The exec window handles raw command execution and history, while the ui window shows clean, user-facing output for interactive sessions.

How to install

Prerequisites you must have before installing this MCP server:

• Node.js 18.0.0 or higher
• tmux installed on your system

Install from npm

npm install -g tmux-mcp-server

Install from source

git clone https://github.com/TNTisdial/persistent-shell-mcp.git
cd persistent-shell-mcp
npm install
npm link

Additional setup and usage notes

Configure your MCP client to connect to the local server through a standard MCP command path. You will create a workspace and then issue commands from the client that run inside the tmux-based environment.

{
  "mcpServers": {
    "tmux-shell": {
      "command": "tmux-mcp-server"
    }
  }
}

Workspaces, execution, and UI windows

Each workspace creates two tmux windows: an exec window for raw shell execution and a ui window for clean, user-facing output. Workspaces are isolated, so processes in one do not affect others.

Troubleshooting tips

If you encounter issues, verify tmux is installed and running, ensure you can create tmux sessions, and check the designated windows are accessible from your MCP client.

Error: tmux command not found

Security and usage notes

This server enables execution of shell commands through an MCP client. Use only in isolated testing environments and on systems that do not contain sensitive data. Do not deploy in production.

Architecture overview

The server maintains separate tmux sessions per workspace. Each session has two windows: exec for command execution and UI for user-facing output. Workspaces are isolated, with independent working directories and environments, preventing cross-talk between projects.

Workspace management workflows

Create a new isolated workspace, run commands in either window, and monitor output or stop processes as needed. Destroy workspaces when they are no longer required to free up resources.

Project examples

Quick command and interactive development patterns help you manage multiple projects in parallel without losing context.

Available tools

execute_command

Run a command in the exec window and return the full output, suitable for quick tasks and quick feedback.

start_process

Start long-running or interactive processes, with the option to target either the exec or ui window for visibility.

get_output

Capture current terminal output from a specified window, allowing you to review results or monitor progress.

send_input

Send text input to a running process in a selected window, enabling interactive sessions.

stop_process

Terminate the currently running process in the exec window by sending a interrupt signal.

create_workspace

Create a new isolated workspace with two windows ready for use.

destroy_workspace

Remove a workspace and all its associated processes.

list_workspaces

List all active workspaces to understand current activity.