Terminal MCP Server enables AI assistants to execute system commands on both local and remote machines via SSH. It provides a secure interface for running shell commands, managing persistent terminal sessions, and configuring command execution environments. Key features: - Execute system commands on the local machine or remotely through SSH connections - Persistent terminal sessions that maintain state and environment variables (default 20-minute timeout) - Custom environment variable configuration for specific command contexts - Dual transport modes: stdio for local integrations and SSE (Server-Sent Events) for remote HTTP access - Configurable SSE server with customizable ports, endpoints, and host bindings - Built-in session management tools for listing and killing active sessions

Terminal MCP Server

Notice 注意事项

*中文文档*

Terminal MCP Server is a Model Context Protocol (MCP) server that allows executing commands on local or remote hosts. It provides a simple yet powerful interface for AI models and other applications to execute system commands, either on the local machine or on remote hosts via SSH.

Features

Installation

Installing via Smithery

To install terminal-mcp-server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @weidwonder/terminal-mcp-server --client claude

Manual Installation

# Clone the repository
git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server
Install dependencies
npm install
Build the project
npm run build

Usage

Starting the Server

# Start the server using stdio (default mode)
npm start
Or run the built file directly
node build/index.js

Starting the Server in SSE Mode

The SSE (Server-Sent Events) mode allows you to connect to the server remotely via HTTP.

# Start the server in SSE mode
npm run start:sse
Or run the built file directly with SSE flag
node build/index.js --sse

You can customize the SSE server with the following command-line options:

| Option | Description | Default | |--------|-------------|---------| | --port or -p | The port to listen on | 8080 | | --endpoint or -e | The endpoint path | /sse | | --host or -h | The host to bind to | localhost |

Example with custom options:

# Start SSE server on port 3000, endpoint /mcp, and bind to all interfaces
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

This will start the server and listen for SSE connections at http://0.0.0.0:3000/mcp.

Testing with MCP Inspector

# Start the MCP Inspector tool
npm run inspector

The execute_command Tool

The execute_command tool is the core functionality provided by Terminal MCP Server, used to execute commands on local or remote hosts.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | command | string | Yes | The command to execute | | host | string | No | The remote host to connect to. If not provided, the command will be executed locally | | username | string | Required when host is specified | The username for SSH connection | | session | string | No | Session name, defaults to "default". The same session name will reuse the same terminal environment for 20 minutes | | env | object | No | Environment variables, defaults to an empty object |

Examples

#### Executing a Command Locally

{
  "command": "ls -la",
  "session": "my-local-session",
  "env": {
    "NODE_ENV": "development"
  }
}

#### Executing a Command on a Remote Host

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "session": "my-remote-session",
  "env": {
    "NODE_ENV": "production"
  }
}

Configuring with AI Assistants

Configuring with Roo Code

1. Open VSCode and install the Roo Code extension 2. Open the Roo Code settings file: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json 3. Add the following configuration:

#### For stdio mode (local connection)

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

#### For SSE mode (remote connection)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Replace localhost:8080/sse with your actual server address, port, and endpoint if you've customized them.

Configuring with Cline

1. Open the Cline settings file: ~/.cline/config.json 2. Add the following configuration:

#### For stdio mode (local connection)

```json { "mcpServers": { "terminal-mcp": { "command": "node", "args": ["/path/to/terminal-mcp-server/build/index.js"], "env":