RemoteShell MCP
🔗 RemoteShell MCP
LLM이 원격 SSH 서버에서 명령을 안전하게 관리하고 실행할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다.
✨ 기능
🔐 안전한 자격 증명 관리 - SSH 서버 프로필을 한 번 저장하면 자격 증명을 다시 입력할 필요가 없습니다
💻 원격 명령 실행 - 비대화형 셸 명령을 원격으로 실행합니다
📁 파일 작업 - SFTP를 통한 파일 업로드/다운로드
🤖 LLM 기반 - FastMCP 및 Paramiko로 구축
Related MCP server: ssh-client-mcp-server
🚀 설치
RemoteShell은 PyPI에 배포되는 stdio MCP 서버입니다. uvx로 직접 실행하세요 — 설치 단계가 필요 없습니다. 그런 다음 서버를 AI 코딩 에이전트에 등록하세요:
Claude Code
claude mcp add remoteshell --scope user -- uvx remoteshell-mcpCodex
codex mcp add remoteshell -- uvx remoteshell-mcp다른 에이전트 — 해당 항목을 클릭하여 펼쳐보세요 👇
cursor mcp add remoteshell -- uvx remoteshell-mcp~/.gemini/config/mcp_config.json(전역) 또는 .agents/mcp_config.json(프로젝트)을 편집하세요:
{
"mcpServers": {
"remoteshell": {
"command": "uvx",
"args": ["remoteshell-mcp"]
}
}
}또는 Antigravity TUI에서 MCP Servers 보기를 열고 /mcp 명령을 실행하세요.
opencode mcp addlocal을 선택한 다음 uvx remoteshell-mcp를 입력하세요.
~/.hermes/config.yaml을 편집하세요:
mcp_servers:
remoteshell:
command: "uvx"
args: ["remoteshell-mcp"]Hermes TUI에서 /reload-mcp를 실행하여 새 서버를 적용하세요.
~/.openclaw/openclaw.json을 편집하세요:
{
"mcp": {
"servers": {
"remoteshell": {
"command": "uvx",
"args": ["remoteshell-mcp"]
}
}
}
}또는 openclaw configure를 실행하여 대화형 마법사로 추가하세요.
MCP 클라이언트 구성에 다음을 추가하세요:
{
"mcpServers": {
"remoteshell": {
"command": "uvx",
"args": ["remoteshell-mcp"]
}
}
}📖 사용법
시작은 간단합니다! 다음 중 하나를 선택하세요:
🤖 LLM이 직접 구성하도록 하기 - LLM에게 호스트, 사용자 이름, 비밀번호 등을 알려주고 서버 구성을 설정하도록 요청하세요
⚙️ 수동 구성 -
~/.config/remoteshell/hosts.json의 구성 파일을 직접 편집하세요
💾 구성 및 저장
RemoteShell은 서버 구성을 안전하게 다음 위치에 저장합니다:
~/.config/remoteshell/hosts.json🔧 구성 관리
LLM 관리: LLM이
save_server및remove_server도구를 사용하여 이 파일을 자동으로 관리합니다수동 편집: 고급 구성을 위해 JSON 파일을 직접 편집할 수도 있습니다
📋 예시 구성
{
"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"
}
}
}🔒 보안 참고 사항
POSIX 시스템에서는 구성 파일을 보호하세요:
chmod 600 ~/.config/remoteshell/hosts.json🛠️ 사용 가능한 도구
RemoteShell은 원격 서버 관리를 위해 다음 MCP 도구를 제공합니다:
📋 list_servers()
용도: 저장된 모든 서버 프로필과 연결 상태 및 마지막 활동을 표시합니다.
사용 시점:
사용자가 "서버에 연결" 또는 "머신 표시"를 요청하는 경우
특정
connection_id가 제공되지 않은 경우사용 가능한 서버를 확인해야 하는 경우
예시: "내가 구성한 서버를 보여줘" → 저장된 모든 서버와 온라인 상태 목록을 반환합니다.
💾 save_server(connection_id, host, user, auth_type, credential, port)
용도: 인증 자격 증명으로 서버 프로필을 생성하거나 업데이트합니다.
매개변수:
connection_id: 서버의 고유 식별자 (예: "production", "staging")host: 서버 호스트명 또는 IP 주소user: SSH 사용자 이름auth_type:"password"또는"private_key"credential:password의 경우: 일반 텍스트 비밀번호 문자열private_key의 경우: 파일 경로(예:~/.ssh/id_rsa) 또는 PEM 키 내용
port: SSH 포트(선택 사항; 기본값은 22이며 생략하면 기존 저장 포트를 유지합니다)
사용 시점:
새 서버 구성을 추가할 때
인증 실패 후 자격 증명을 업데이트할 때
서버 연결 세부 정보를 변경할 때
🗑️ remove_server(connection_id)
용도: 저장소에서 서버 프로필을 영구적으로 삭제합니다.
사용 시점:
사용자가 서버 제거 또는 삭제를 명시적으로 요청하는 경우
서버에 더 이상 접근할 수 없거나 필요하지 않은 경우
⚠️ 경고: 이 작업은 되돌릴 수 없습니다
⚡ execute_command(connection_id, command)
용도: 비대화형 셸 명령을 원격으로 실행하고 결과를 반환합니다.
반환값: stdout, stderr, exit_code
사용 시점:
시스템 명령, 스크립트 또는 유틸리티를 실행할 때
서버 상태, 디스크 사용량, 프로세스 목록을 확인할 때
파일 작업, 패키지 관리 등을 수행할 때
사용하지 말아야 할 경우:
대화형 프로그램(vim, htop, top)
수동 입력이 필요한 명령(
[Y/n]프롬프트) --y같은 플래그를 사용하지 않는 한
예시: execute_command(connection_id="production", command="df -h")
📤 upload_file(connection_id, local_path, remote_path)
용도: SFTP를 통해 로컬 머신에서 원격 서버로 파일을 업로드합니다.
매개변수:
local_path: 로컬 머신에 있는 파일의 경로remote_path: 원격 서버의 대상 경로
참고 사항:
remote_path가 디렉터리인 경우 원본 파일 이름이 유지됩니다local_path를 생략하면 서버가 기본값을 선택하고 응답에 반환합니다
📥 download_file(connection_id, remote_path, local_path)
용도: SFTP를 통해 원격 서버에서 로컬 머신으로 파일을 다운로드합니다.
매개변수:
remote_path: 원격 서버에 있는 파일의 경로local_path: 로컬 머신의 대상 경로
참고 사항:
local_path를 생략하면 기본값은~/.config/remoteshell/downloads/<connection_id>/<basename>입니다
🧪 개발
로컬 개발 설정
로컬 개발에는 다음 MCP 구성을 사용하세요:
{
"mcpServers": {
"remoteshell": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/remoteShell-mcp", "run", "remoteshell-mcp"]
}
}
}테스트 실행
uv run pytestAvailable Tools
6 toolsdownload_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/")
| Name | Required | Description | Default |
|---|---|---|---|
| local_path | No | Local destination path. Defaults to ~/.config/remoteshell/downloads/<connection_id>/ | |
| remote_path | Yes | Path to the remote file to download | |
| connection_id | Yes | Unique identifier of the server connection |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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")
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to execute (non-interactive only) | |
| connection_id | Yes | Unique identifier of the server connection |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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."
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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")
| Name | Required | Description | Default |
|---|---|---|---|
| connection_id | Yes | Unique identifier of the server to remove |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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)
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Server hostname or IP address | |
| port | No | SSH port. Defaults to 22. If omitted, keeps the existing saved port (if any). | |
| user | Yes | SSH username | |
| auth_type | Yes | Authentication method: 'password' or 'private_key' | |
| credential | Yes | Password for 'password' auth, or path/PEM text for 'private_key' auth | |
| connection_id | Yes | Unique identifier for this server connection |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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/")
| Name | Required | Description | Default |
|---|---|---|---|
| local_path | No | Local file path to upload. Defaults to a path in ~/.config/remoteshell/uploads/ | |
| remote_path | Yes | Destination path on the remote server | |
| connection_id | Yes | Unique identifier of the server connection |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v1.1.1- First observed
download_file - First observed
execute_command - First observed
list_servers - First observed
remove_server - First observed
save_server - First observed
upload_file
TDQS
Scored across 6 tools
Each tool has a distinct purpose: server profile management (save, list, remove) and remote operations (execute, upload, download). No overlap or ambiguity.
All tools follow a consistent verb_noun pattern (e.g., remove_server, list_servers, execute_command), making them predictable and easy to use.
6 tools is well-scoped for a remote shell MCP, covering server management and core file/command operations without superfluous tools.
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
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
- emisarOAuthdev.emisar
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Related MCP Servers
- FlicenseAqualityDmaintenanceA local Model Context Protocol server that allows LLMs to securely execute shell commands on remote Linux and Windows systems via SSH connections.65 npm2-
- AlicenseNot gradedqualityBmaintenanceA local MCP server that enables LLMs to execute shell commands on remote hosts over SSH with multiple authentication methods.35 npm3MIT
- AlicenseNot gradedqualityDmaintenanceA centralized MCP server that enables LLM agents to securely execute commands and manage Linux servers via SSH.2MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that enables LLMs to execute shell commands on remote Linux and Windows systems via SSH with configurable timeout and authentication options.3,891 npmMIT