Skip to main content
Glama
chouzz

RemoteShell MCP

by chouzz

๐Ÿ”— RemoteShell MCP

A Model Context Protocol (MCP) server that enables LLMs to securely manage and execute commands on remote SSH servers.

โœจ Features

  • ๐Ÿ” Secure credential management - Save SSH server profiles once, no need to retype credentials

  • ๐Ÿ’ป Remote command execution - Execute non-interactive shell commands remotely

  • ๐Ÿ“ File operations - Upload/download files via SFTP

  • ๐Ÿค– LLM-powered - Built with FastMCP and Paramiko

Related MCP server: SSH MCP Server

๐Ÿš€ Installation

RemoteShell is a stdio MCP server distributed on PyPI. Run it directly with uvx โ€” no install step required. Then register the server with your AI coding agent:

Claude Code

claude mcp add remoteshell --scope user -- uvx remoteshell-mcp

Codex

codex mcp add remoteshell -- uvx remoteshell-mcp

Other agents โ€” click yours to expand ๐Ÿ‘‡

cursor mcp add remoteshell -- uvx remoteshell-mcp

Edit ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (project):

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

Or open the MCP Servers view in the Antigravity TUI and run the /mcp command.

opencode mcp add

Choose local, then enter uvx remoteshell-mcp.

Edit ~/.hermes/config.yaml:

mcp_servers:
  remoteshell:
    command: "uvx"
    args: ["remoteshell-mcp"]

Run /reload-mcp in the Hermes TUI to pick up the new server.

Edit ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "remoteshell": {
        "command": "uvx",
        "args": ["remoteshell-mcp"]
      }
    }
  }
}

Or run openclaw configure to add it via the interactive wizard.

Add this to your MCP client configuration:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

๐Ÿ“– Usage

Getting started is easy! You can either:

  1. ๐Ÿค– Let the LLM configure for you - Simply tell the LLM your host, username, password, etc., and ask it to set up the server configuration

  2. โš™๏ธ Manual configuration - Directly edit the configuration file at ~/.config/remoteshell/hosts.json

๐Ÿ’พ Configuration & Storage

RemoteShell securely stores your server configurations in:

~/.config/remoteshell/hosts.json

๐Ÿ”ง Configuration Management

  • LLM-managed: The LLM automatically manages this file using save_server and remove_server tools

  • Manual editing: You can also directly edit the JSON file for advanced configurations

๐Ÿ“‹ Example Configuration

{
  "version": 1,
  "servers": {
    "production-server": {
      "host": "1.2.3.4",
      "user": "root",
      "port": 22,
      "auth_type": "password",
      "password": "your_secure_password",
      "last_connected": null
    },
    "staging-server": {
      "host": "staging.example.com",
      "user": "ubuntu",
      "port": 22,
      "auth_type": "private_key",
      "private_key": "~/.ssh/id_rsa",
      "last_connected": "2025-01-01T00:00:00+00:00"
    }
  }
}

๐Ÿ”’ Security Note

On POSIX systems, protect your configuration file:

chmod 600 ~/.config/remoteshell/hosts.json

๐Ÿ› ๏ธ Available Tools

RemoteShell provides the following MCP tools for remote server management:

๐Ÿ“‹ list_servers()

Purpose: Display all saved server profiles with their connection status and last activity.

When to use:

  • User asks to "connect to server" or "show machines"

  • No specific connection_id is provided

  • Need to see available servers

Example: "Show me which servers I have configured" โ†’ Returns list of all saved servers with online status

๐Ÿ’พ save_server(connection_id, host, user, auth_type, credential, port)

Purpose: Create or update a server profile with authentication credentials.

Parameters:

  • connection_id: Unique identifier for the server (e.g., "production", "staging")

  • host: Server hostname or IP address

  • user: SSH username

  • auth_type: "password" or "private_key"

  • credential:

    • For password: Plain text password string

    • For private_key: File path (e.g., ~/.ssh/id_rsa) or PEM key content

  • port: SSH port (optional; defaults to 22 and keeps the existing saved port if omitted)

When to use:

  • Adding a new server configuration

  • Updating credentials after authentication failure

  • Changing server connection details

๐Ÿ—‘๏ธ remove_server(connection_id)

Purpose: Permanently delete a server profile from storage.

When to use:

  • User explicitly requests to remove or forget a server

  • Server is no longer accessible or needed

โš ๏ธ Warning: This action cannot be undone

โšก execute_command(connection_id, command)

Purpose: Execute non-interactive shell commands remotely and return results.

Returns: stdout, stderr, and exit_code

When to use:

  • Running system commands, scripts, or utilities

  • Checking server status, disk usage, process lists

  • File operations, package management, etc.

When NOT to use:

  • Interactive programs (vim, htop, top)

  • Commands requiring manual input ([Y/n] prompts) - unless using flags like -y

Example: execute_command(connection_id="production", command="df -h")

๐Ÿ“ค upload_file(connection_id, local_path, remote_path)

Purpose: Upload files from your local machine to a remote server via SFTP.

Parameters:

  • local_path: Path to the file on your local machine

  • remote_path: Destination path on the remote server

Notes:

  • If remote_path is a directory, the original filename is preserved

  • If local_path is omitted, server selects a default and returns it in response

๐Ÿ“ฅ download_file(connection_id, remote_path, local_path)

Purpose: Download files from a remote server to your local machine via SFTP.

Parameters:

  • remote_path: Path to the file on the remote server

  • local_path: Destination path on your local machine

Notes:

  • If local_path is omitted, defaults to: ~/.config/remoteshell/downloads/<connection_id>/<basename>

๐Ÿงช Development

Local Development Setup

For local development, use this MCP configuration:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/remoteShell-mcp", "run", "remoteshell-mcp"]
    }
  }
}

Running Tests

uv run pytest

Available Tools

6 tools
download_fileA

Download a remote file to a local path (on the machine running this MCP server) via SFTP.

When to use: Fetch logs, reports, or backups from the remote. When NOT to use: Avoid very large downloads (>100MB) unless you verified size first.

Example: download_file(connection_id="srv1", remote_path="/var/log/syslog", local_path="./logs/")

ParametersJSON Schema
NameRequiredDescriptionDefault
local_pathNoLocal destination path. Defaults to ~/.config/remoteshell/downloads/<connection_id>/
remote_pathYesPath to the remote file to download
connection_idYesUnique identifier of the server connection

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It mentions SFTP, default local path, and warns about large files. However, it lacks details on overwrite behavior, directory creation, error handling, or authentication requirements, which are important for a file download tool.

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

Conciseness5/5

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

The description is three sentences and an example, all essential. First sentence states purpose, second gives usage guidelines, third is an example. No wasted words, well-structured.

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

Completeness4/5

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

The tool has 3 parameters with full schema coverage, usage guidelines, and a size warning. An output schema exists, so return values need not be described. However, missing details like overwrite behavior and error handling slightly reduce completeness.

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?

Schema description coverage is 100%, so baseline is 3. The description adds little beyond schema: it restates default for local_path in prose and provides an example. No additional semantics for connection_id or remote_path.

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

Purpose5/5

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

The description clearly states 'Download a remote file to a local path via SFTP.' This specifies the action (download), the resource (remote file), and the protocol (SFTP). It distinguishes from sibling tools like upload_file (opposite direction) and execute_command (command execution).

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

Usage Guidelines5/5

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

The description explicitly says 'When to use: Fetch logs, reports, or backups' and 'When NOT to use: Avoid very large downloads (>100MB) unless you verified size first.' This provides clear context and a size limitation, guiding the agent on appropriate usage.

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

execute_commandA

Execute a non-interactive shell command on a remote server and return stdout/stderr/exit_code.

When to use: Status checks (df, ls), file ops (cp, mv), and scripts that do not require live interaction. When NOT to use: Do not run interactive tools (vim, htop, top) or commands that require manual prompts.

Example: execute_command(connection_id="srv1", command="df -h")

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesShell command to execute (non-interactive only)
connection_idYesUnique identifier of the server connection

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

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

No annotations exist, so description must cover behavior. It states non-interactive and returns, but does not explicitly disclose potential for server mutation (e.g., cp, mv modify files). Could be clearer about destructive potential.

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

Conciseness5/5

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

Four lines with purpose, usage guidance, and example. Every sentence earns its place, well-structured and front-loaded.

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

Completeness4/5

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

Given output schema exists, return values need not be explained. Covers usage context and parameter roles. Lacks mention of error/timeout handling but adequate.

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?

Schema coverage is 100% with clear descriptions. The description adds only example and non-interactive context, which is marginal beyond schema. Baseline 3 is appropriate.

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

Purpose5/5

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

Clearly states 'Execute a non-interactive shell command on a remote server and return stdout/stderr/exit_code.' Specific verb and resource, distinguishes from sibling tools like upload_file or remove_server.

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

Usage Guidelines5/5

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

Provides explicit when-to-use (status checks, file ops, scripts) and when-NOT-to-use (interactive tools like vim, htop), plus a concrete example.

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

list_serversA

List all servers saved locally by this MCP server (persistent inventory).

When to use: When the user asks to connect to a server, manage machines, or did not specify a connection_id. When NOT to use: Not needed if you already know the correct connection_id.

Example: "Show me which servers I have."

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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

Although no annotations are provided, the description transparently states the tool reads from a 'persistent inventory' and does not indicate destructive behavior. It reasonably covers the safety profile for a read-only list operation.

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

Conciseness5/5

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

Extremely concise: two sentences plus structured when/when-not guidelines. Every sentence adds value, and the purpose is front-loaded. No unnecessary words.

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

Completeness5/5

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

Given zero parameters and an output schema that documents return values, the description fully equips the agent: it explains purpose, usage boundaries, and provides an example. No gaps remain.

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

Parameters4/5

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

There are zero parameters; the schema coverage is 100% (no parameters). Per guidelines, baseline for 0 parameters is 4. The description adds no parameter info, but none is needed.

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

Purpose5/5

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

The description explicitly states 'List all servers saved locally by this MCP server (persistent inventory)', using a specific verb and resource. It clearly distinguishes from sibling tools that add, remove, or execute actions.

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

Usage Guidelines5/5

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

Provides explicit 'When to use' and 'When NOT to use' conditions, including an alternative (using a known connection_id) and an example query. This gives clear guidance for the agent.

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

remove_serverA

Permanently delete a saved server profile from the local host store.

When to use: Only when the user explicitly asks to forget/remove a server. When NOT to use: Do not remove servers just because a connection failed.

Example: remove_server(connection_id="srv1")

ParametersJSON Schema
NameRequiredDescriptionDefault
connection_idYesUnique identifier of the server to remove

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. States 'permanently delete' indicating irreversibility. Could mention error handling for missing server, but sufficient for a simple delete.

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

Conciseness5/5

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

Short, front-loaded: purpose first, then guidelines, then example. No wasted words.

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

Completeness5/5

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

Simple tool with one param and output schema. Description covers purpose, usage guidelines, and example adequately.

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

Parameters4/5

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

Schema already covers 'connection_id' with description. The example usage adds practical context beyond schema.

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

Purpose5/5

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

States 'Permanently delete a saved server profile' with specific verb and resource. Distinct from siblings like list_servers and execute_command.

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

Usage Guidelines5/5

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

Explicitly says when to use ('only when user asks to forget/remove') and when NOT to use ('not just because connection failed'). Provides clear context and exclusion.

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

save_serverA

Persist (create or update) a server connection profile in the local host store.

When to use: When the user provides new SSH details, or after an auth_failed error to update credentials. When NOT to use: Do not ask for credentials again if they are already saved and still valid.

Example: save_server(connection_id="srv1", host="1.2.3.4", user="root", auth_type="password", credential="", port=2222)

ParametersJSON Schema
NameRequiredDescriptionDefault
hostYesServer hostname or IP address
portNoSSH port. Defaults to 22. If omitted, keeps the existing saved port (if any).
userYesSSH username
auth_typeYesAuthentication method: 'password' or 'private_key'
credentialYesPassword for 'password' auth, or path/PEM text for 'private_key' auth
connection_idYesUnique identifier for this server connection

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It indicates mutation (create/update) and local persistence, but does not disclose side effects (e.g., whether existing connection_id is overwritten), authentication requirements beyond schema, or rate limits. Adequate but not detailed.

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

Conciseness5/5

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

Three sentences plus an example, front-loaded with purpose, then usage context. No fluff; every sentence earns its place.

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

Completeness4/5

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

Given the tool has 6 parameters (5 required) and an output schema (not shown but exists), the description covers usage context well. Could mention the return value (e.g., confirmation of save) but not required since output schema exists. Slightly above adequate.

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?

Schema description coverage is 100%, so baseline is 3. The description does not add new param semantics beyond the example; the schema already covers each parameter well. No extra value provided.

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

Purpose5/5

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

The description clearly states 'Persist (create or update) a server connection profile in the local host store', using a specific verb ('persist') and resource ('server connection profile'). It also contrasts with sibling tools like 'remove_server' and 'list_servers' by focusing on creation/update.

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

Usage Guidelines5/5

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

Explicitly states when to use ('new SSH details, or after an auth_failed error to update credentials') and when NOT to use ('Do not ask for credentials again if they are already saved and still valid'). Includes a concrete example.

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

upload_fileA

Upload a local file (on the machine running this MCP server) to a remote server via SFTP.

When to use: Deploy configs, scripts, or artifacts to the remote. When NOT to use: Do not upload huge files blindly; verify size/permissions first.

Example: upload_file(connection_id="srv1", local_path="./config.yaml", remote_path="/etc/app/")

ParametersJSON Schema
NameRequiredDescriptionDefault
local_pathNoLocal file path to upload. Defaults to a path in ~/.config/remoteshell/uploads/
remote_pathYesDestination path on the remote server
connection_idYesUnique identifier of the server connection

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations, description carries full burden. It mentions SFTP and cautions about large files, but does not specify whether uploads overwrite existing files, preserve timestamps, or handle permissions. Moderate transparency.

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

Conciseness5/5

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

Very concise with three short sentences and an example. No fluff. Front-loaded with the core action. Well-structured.

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

Completeness4/5

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

Covers purpose, usage, and example. Output schema exists, so return values are handled. Lacks mention of file overwriting or error conditions, but overall sufficient for a straightforward upload tool.

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?

Schema coverage is 100%, so baseline is 3. The description adds an example call but no additional semantic detail beyond schema. No bonus or penalty.

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

Purpose5/5

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

The description clearly states the action: 'Upload a local file...to a remote server via SFTP.' This is a specific verb-resource combination that distinguishes it from siblings like download_file or execute_command.

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

Usage Guidelines5/5

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

Provides explicit 'When to use' (deploy configs, scripts, artifacts) and 'When NOT to use' (avoid blind upload of huge files; verify size/permissions). This offers clear context for decision-making.

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. Dates show when Glama detected each change.

  1. 6 tool updatesv1.1.1
    • First observeddownload_file
    • First observedexecute_command
    • First observedlist_servers
    • First observedremove_server
    • First observedsave_server
    • First observedupload_file

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: server profile management (save, list, remove) and remote operations (execute, upload, download). No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (e.g., remove_server, list_servers, execute_command), making them predictable and easy to use.

Tool Count5/5

6 tools is well-scoped for a remote shell MCP, covering server management and core file/command operations without superfluous tools.

Completeness4/5

Covers key CRUD operations for servers and essential remote actions (execute, upload, download). Minor gap: no explicit test-connection or update server operation, but save_server handles updates.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    D
    maintenance
    A local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.
    6
    17
    2
    -
  • A
    license
    A
    quality
    A
    maintenance
    A Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH. It supports password and key-based authentication, command timeouts, and sudo elevation for administrative tasks.
    11
    14,123
    688
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A centralized MCP server that enables LLM agents to securely execute commands and manage Linux servers via SSH.
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/chouzz/remoteShell-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server