Terminal MCP Server

Terminal MCP Server is an MCP protocol server that supports command execution on local and remote hosts, providing a system command operation interface for AI models.

Operating system automation Developer tools #Command execution #SSH connection #Session management #AI integration Remote .TypeScript

rating : 2.5 points

downloads : 21

update time : 2025-04-23

What is Terminal MCP Server?

Terminal MCP Server is a tool that enables AI models to safely execute system commands through a standard protocol. It supports both local command execution and command execution on remote hosts via SSH connection, serving as a bridge for AI assistants to interact with the operating system.

How to use Terminal MCP Server?

After installation, you can let the AI assistant execute system commands through simple JSON instructions. Two connection methods are supported: direct local connection (stdio) or remote HTTP connection (SSE).

Applicable scenarios

Suitable for scenarios where AI assistants are needed to perform system management tasks, automate scripts, and perform file operations. It is especially suitable for developers and system administrators to use AI for auxiliary work.

Main features

Local command executionExecute system commands directly on the machine where the server is installed.

Remote SSH executionConnect to a remote host via SSH to execute commands.

Session persistenceMaintain the same terminal environment within 20 minutes, suitable for continuous operations.

Environment variable supportCustom environment variables can be set for commands.

Multiple connection methodsSupports stdio local connection and SSE remote HTTP connection.

Advantages and limitations

Advantages

A unified command execution interface simplifies the interaction between AI models and the system.

Supports local and remote operations, with flexible usage scenarios.

The session persistence function ensures the environment consistency of continuous commands.

Multiple connection methods meet different deployment requirements.

Limitations

Remote SSH requires pre - configured key authentication.

Command execution permissions are limited to the permissions of the user running the server.

The session has a 20 - minute timeout limit.

Requires a Node.js runtime environment.

How to use

Install the server

Install via npm or build from source code.

Start the server

Select a suitable connection method to start the server.

Configure the AI client

Add the MCP server connection information to the AI assistant configuration file.

Start using

Send a JSON - formatted command request through the AI assistant.

Usage examples

Local file managementLet the AI assistant list and analyze local files.

Remote server monitoringCheck the disk usage of a remote server.

Development environment setupRun the test suite in the development environment.

Frequently Asked Questions

How to ensure the security of command execution?

What is the difference between SSE mode and stdio mode?

What happens after the session times out?

Does it support the Windows system?

Related resources

GitHub repository

Project source code and the latest version.

Smithery platform

Automated installation and update services.

MCP protocol documentation

Official documentation of the Model Context Protocol.

🚀 Terminal MCP Server

The Terminal MCP Server is a server based on the Model Context Protocol (MCP), which allows commands to be executed remotely or locally. It supports remote command execution via SSH connections and can run commands in the local environment.

🚀 Quick Start

The Terminal MCP Server enables users to execute commands either remotely or locally. It offers a convenient way to manage command - line operations across different environments.

✨ Features

Remote Command Execution: Connect to remote devices via the SSH protocol and execute commands.
Local Command Execution: Run commands directly in the local environment where the server is started.
Session Management: Provide an active session of 20 minutes to maintain the consistency of the environment context.
Multi - platform Compatibility: Support multiple operating systems such as Mac and Linux.

📦 Installation

Install via Smithery

Use the provided link to directly install the Terminal MCP Server on the Smithery platform.

Manual Installation

Clone the project repository:

git clone https://github.com/weidwonder/terminal-mcp-server.git

Navigate to the project directory and install dependencies:

cd terminal-mcp-server
npm install

💻 Usage Examples

Start the Server

Local Mode (without SSH):

node index.js --local

Remote Mode (with SSH enabled):

node index.js --ssh

Connect via SSH

Ensure that the target device has SSH key authentication configured. By default, the server will attempt to use the ~/.ssh/id_rsa key for connection.

Execute Commands

Local Execution

Run commands directly in the started server environment:

execute_command --local "your command"

Remote Execution

Run commands on the target device connected via SSH:

execute_command --ssh <target-host> "your command"

`execute_command` Tool

Parameter Description

Property	Details
`--local`	Execute commands in the local environment
`--ssh`	Connect to a remote device via SSH and execute commands
`<target-host>`	Address of the remote target host (only used in SSH mode)
`"your command"`	Specific command to be executed

Examples

Run a simple command locally:

execute_command --local "echo 'Hello, World!'"

Execute complex tasks on a remote device:

execute_command --ssh 192.168.1.100 "sudo apt update && sudo apt upgrade"

📚 Documentation

Best Practices

Command Execution

Adjust commands according to the target system type (Mac, Linux, etc.).
Use full paths to avoid dependency issues.
For multi - step operations that require maintaining the environment, use && to connect commands.

SSH Connection

Configure SSH key authentication in advance.
Check if the key file exists (default: ~/.ssh/id_rsa).
Ensure that the SSH service on the remote device is running properly.

Session Management

Use the --local or --ssh parameter to maintain the environment context.
It is recommended to keep the same session for complex operations to maintain environment consistency.
The connection will be automatically disconnected after 20 minutes of inactivity.

Important Notes

⚠️ Important Note

Ensure the security of the target device when executing commands remotely.

💡 Usage Tip

The permissions of local or remote commands depend on the user identity starting the server and the SSH connection. Long - running tasks may require additional resource management and monitoring.