TerminusAI
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TerminusAI list files in my home directory on server1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TerminusAI – a final stop for all terminal tasks, AI-driven
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)
Related MCP server: Interactive Shell MCP
Installation
Installing via Smithery
To install TerminusAI-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @Gorav22/TerminusAI --client claudeManual Installation
# Clone the repository
git clone https://github.com/Gorav/TerminusAI.git
cd TerminusAI
# Install dependencies
npm install
# Build the project
npm run buildUsage
Starting the Server
# Start the server using stdio (default mode)
npm start
# Or run the built file directly
node build/index.jsStarting 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 --sseYou can customize the SSE server with the following command-line options:
Option | Description | Default |
| The port to listen on | 8080 |
| The endpoint path | /sse |
| 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.0This 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 inspectorThe 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"//add any other env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}Configuring with AI Assistants
For stdio mode (local connection)
{
"mcpServers": {
"TerminusAI": {
"command": "node",
"args": ["/path/to/TerminusAI-server/build/index.js"],
"env": {}//add env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}
}For SSE mode (remote connection)
{
"mcpServers": {
"TerminusAI-sse": {
"url": "http://localhost:8080/sse",
"headers": {}//add env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}
}Replace localhost:8080/sse with your actual server address, port, and endpoint if you've customized them.
Configuring with Cline
Open the Cline settings file:
~/.cline/config.jsonAdd the following configuration:
For stdio mode (local connection)
{
"mcpServers": {
"TerminusAI": {
"command": "node",
"args": ["/path/to/TerminusAI-server/build/index.js"],
"env": {}//add env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}
}For SSE mode (remote connection)
{
"mcpServers": {
"TerminusAI-sse": {
"url": "http://localhost:8080/sse",
"headers": {}//add env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}
}Configuring with Claude Desktop
Open the Claude Desktop settings file:
C:\Users\HP\AppData\Roaming\Claude\claude_desktop_config.jsonAdd the following configuration:
For stdio mode (local connection)
{
"mcpServers": {
"TerminusAI": {
"command": "node",
"args": ["/path/to/TerminusAI-server/build/index.js"],
"env": {} //add env variables if your terminal code needs that like in linux if your command wants to use root or admin piower for which its password is needed then mention that in env and also tell to llm about that or it automatic scans and come to know that.
}
}
}For SSE mode (remote connection)
{
"mcpServers": {
"TerminusAI-sse": {
"url": "http://localhost:8080/sse",
"headers": {}
}
}
}Best Practices
Command Execution
Before running commands, it's best to determine the system type (Windows, Linux, etc.)
Use full paths to avoid path-related issues
For command sequences that need to maintain environment, use
&&to connect multiple commandsFor long-running commands, consider using
nohuporscreen/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
Available Tools
1 toolexecute_commandB
Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)
Inputs: command (required), host, username, session, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clear and distinct purpose.
Since there is only one tool, naming consistency is inherently perfect. The tool name follows a clear verb_noun pattern.
A single tool is too few for a server named 'TerminusAI', which suggests a broader scope like remote command execution or system management. This minimal set lacks the depth expected for such a domain.
The tool surface is severely incomplete for the implied domain. It only provides command execution with no support for listing hosts, managing connections, checking status, or handling outputs, leaving significant gaps for agent workflows.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides stateful, interactive terminal access for LLMs to spawn and maintain persistent processes like SSH sessions, debuggers, and REPLs with continuous input/output interaction across commands.8-
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to create and manage persistent, interactive shell sessions with full terminal emulation and PTY support. It allows for sequential command execution and supports interactive programs like vim or htop through specialized streaming and snapshot output modes.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.14 npm2MIT
- AlicenseAqualityBmaintenanceExposes persistent, stateful remote Bash sessions to AI agents via SSH, enabling command execution with preserved working directory and environment.763 npm1MIT