Terminal MCP Server

中文文档

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

• Local Command Execution: Execute commands directly on the local machine
• Remote Command Execution: Execute commands on remote hosts via SSH
• Session Persistence: Support for persistent sessions that reuse the same terminal environment for a specified time (default 20 minutes)
• Environment Variables: Set custom environment variables for commands
• Multiple Connection Methods: Connect via stdio or SSE (Server-Sent Events)

Installation

Installing via Smithery

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

Manual Installation

Usage

Starting the Server

Starting the Server in SSE Mode

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

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

Example with custom options:

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

Testing with MCP 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

Examples

Executing a Command Locally

Executing a Command on a Remote Host

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)

For SSE mode (remote connection)

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)

For SSE mode (remote connection)

Configuring with Claude Desktop

1. Open the Claude Desktop settings file: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the following configuration:

For stdio mode (local connection)

For SSE mode (remote connection)

Best Practices

Command Execution

• Before running commands, it's best to determine the system type (Mac, Linux, etc.)
• Use full paths to avoid path-related issues
• For command sequences that need to maintain environment, use && to connect multiple commands
• For long-running commands, consider using nohup or screen/tmux

SSH Connection

• Ensure SSH key-based authentication is set up
• If connection fails, check if the key file exists (default path: ~/.ssh/id_rsa)
• Make sure the SSH service is running on the remote host

Session Management

• Use the session parameter to maintain environment between related commands
• For operations requiring specific environments, use the same session name
• Note that sessions will automatically close after 20 minutes of inactivity

Error Handling

• Command execution results include both stdout and stderr
• Check stderr to determine if the command executed successfully
• For complex operations, add verification steps to ensure success

Important Notes

• For remote command execution, SSH key-based authentication must be set up in advance
• For local command execution, commands will run in the context of the user who started the server
• Session timeout is 20 minutes, after which the connection will be automatically closed