Terminal MCP Server provides a programmable interface to execute commands on the local machine or remote hosts via SSH, with optional persistent sessions. It supports stdio connections for local use and SSE (Server-Sent Events) for remote, event-driven interactions. You can run commands directly, reuse a session to maintain a consistent environment for up to 20 minutes, and inject environment variables for specific runs. The core tool, execute_command, accepts a command string and optional host, username, session name, and environment variables, enabling both local and remote command execution in a single, email-friendly API.

To use, start the server in stdio mode for local operations or SSE mode for remote access. When using SSE, you can connect via HTTP to an endpoint like /sse and pass credentials or headers as needed. The server exposes the execute_command capability so AI models or applications can issue commands, with stdout and stderr captured for inspection. For long-running tasks, leverage session persistence to maintain context across related commands and reuse the same shell state.

Prerequisites:

• Node.js installed (recommended LTS version)
• Git installed

Manual installation:

1. Clone the repository git clone https://github.com/weidwonder/terminal-mcp-server.git cd terminal-mcp-server

2. Install dependencies npm install

3. Build the project (if a build step exists in the repository) npm run build

4. Run the server (stdio mode) npm start

   or, if you prefer the built file directly

   node build/index.js

5. Run the server in SSE mode (remote access) npm run start:sse

   or, run the built file with SSE flag

   node build/index.js --sse

Prerequisites note: Ensure the environment has access to SSH keys for remote execution and that any required system dependencies for commands you plan to run are installed on the host.

Tips and caveats:

• For remote executions, ensure SSH key-based authentication is set up and that the key file exists at the default location (~/.ssh/id_rsa) unless configured otherwise.
• Session timeout is 20 minutes of inactivity; plan to reuse or renew sessions for long-running tasks.
• Use explicit absolute paths for commands or binaries to avoid PATH-related issues.
• When using SSE, configure host, port, and endpoint according to your deployment, and supply any necessary headers for authentication.
• Environment variables can be injected per command via the env object to customize behavior per run.
• Error handling: both stdout and stderr are returned; check stderr to verify success and add additional verification steps when needed.