Terminal MCP Server

🚀 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

1. Clone the project repository:

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

2. 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

Examples

1. Run a simple command locally:

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

2. 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.