Skip to main content
Glama
Gorav22

TerminusAI

by Gorav22
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

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 claude

Manual Installation

# Clone the repository
git clone https://github.com/Gorav/TerminusAI.git
cd TerminusAI

# 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"//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

  1. Open the Cline settings file: ~/.cline/config.json

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

  1. Open the Claude Desktop settings file: C:\Users\HP\AppData\Roaming\Claude\claude_desktop_config.json

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

Available Tools

1 tool
execute_commandB

Execute commands on remote hosts or locally (This tool can be used for both remote hosts and the current machine)

ParametersJSON Schema
NameRequiredDescriptionDefault
hostNoHost to connect to (optional, if not provided the command will be executed locally)
usernameNoUsername for SSH connection (required when host is specified)
sessionNoSession name, defaults to 'default'. The same session name will reuse the same terminal environment for 20 minutes, which is useful for operations requiring specific environments like conda.default
commandYesCommand to execute. Before running commands, it's best to determine the system type (Mac, Linux, etc.)
envNoEnvironment variables

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that commands can be executed remotely or locally and hints at session reuse for 20 minutes, but it lacks critical details such as security implications, error handling, output format, or potential side effects. This leaves significant gaps for a tool that executes arbitrary commands.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core functionality. It avoids unnecessary details and stays focused on the tool's scope, though it could be slightly more structured by explicitly separating remote and local use cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of executing commands (which can have security and system impacts), the lack of annotations, and no output schema, the description is insufficient. It fails to address critical aspects like return values, error conditions, or safety warnings, making it incomplete for informed tool usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description does not add any meaningful parameter semantics beyond what is already documented in the schema, such as explaining the 'command' parameter's system dependencies or the 'session' parameter's environmental implications in more depth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as executing commands on remote hosts or locally, specifying both the verb ('execute') and the resource ('commands'). It distinguishes between remote and local execution contexts. However, without sibling tools, it cannot demonstrate differentiation from alternatives, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning both remote and local contexts, but it does not provide explicit guidance on when to choose one over the other or any prerequisites. For example, it notes host is optional for local execution but does not clarify when remote execution is preferable or what conditions might affect it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool update
    • First observedexecute_command
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clear and distinct purpose.

Naming Consistency5/5

Since there is only one tool, naming consistency is inherently perfect. The tool name follows a clear verb_noun pattern.

Tool Count2/5

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.

Completeness1/5

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Interactive Shell MCP

    lightos
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables 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.
    5
    MIT

  • mcp-ssh-terminal

    zhdkirill
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
    15 npm
    1
    MIT

  • Remote SSH MCP

    the-nine-nation
    A
    license
    A
    quality
    A
    maintenance
    Exposes persistent, stateful remote Bash sessions to AI agents via SSH, enabling command execution with preserved working directory and environment.
    7
    34 npm
    1
    MIT

Appeared in Searches