terminal

The Terminal MCP Server provides a dual-mode command execution framework. It can run commands locally on the host where the server is running, or remotely on other machines via SSH using details inferred from your ~/.ssh/config. It understands SSH alias configurations, managing persistent sessions with configurable timeouts, and supports passing environment variables to both local and remote commands. The server exposes a tool named execute_command that lets your AI models or applications issue shell commands, optionally targeting a remote host by its SSH alias. If you omit the host, commands execute locally. The server also reuses SSH connections to reduce overhead, and it provides robust error handling and retry capabilities for reliability.

Prerequisites:

• Node.js (and npm) installed on your machine
• Git installed
• Access to a terminal or shell environment

Installation steps:

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

2. Install dependencies: npm install

3. Build the project (if required by the project workflow): npm run build

4. Start the MCP server: npm start

Notes:

• You can set DEFAULT_DIR to influence local command working directory before starting the server, e.g.: DEFAULT_DIR="/workdir" npm start
• Ensure your SSH config (~/.ssh/config) is properly set up for any remote hosts you intend to access.

Tips and considerations:

• SSH Configuration: The server relies on your existing SSH configuration. It will parse Host entries from ~/.ssh/config to determine HostName, User, IdentityFile, Port, etc.
• Environment Variables: Use env to pass variables to commands. Consider exposing sensitive data securely (avoid hard-coding secrets).
• Default Directory: If you frequently operate from a specific local directory, set DEFAULT_DIR to streamline local command execution.
• Local vs Remote: When host is omitted in execute_command, commands run locally. Provide a host alias to run remotely via SSH.
• Troubleshooting: If commands fail due to permissions or missing binaries, verify PATH and user permissions on both local and remote hosts. Check SSH key access and agent availability if using key-based authentication.