de en es ja ko ru zh

SSH Remote File MCP Server

Name: SSH Remote File MCP Server
Author: zhangqi-eiq

by zhangqi-eiq

Overview Schema Source Related Servers Discussions Admin

Python

Remote

SSH 원격 파일 MCP 서버

Claude Code를 통해 원격 서버에서 파일을 읽고, 편집하고, 명령을 실행하세요 — 마치 로컬 파일인 것처럼.

원격 SSH 호스트를 파일 시스템 도구 모음으로 노출하는 MCP 서버입니다. Claude Code에 등록하면 /home/you/proj/main.py 읽기, 함수 편집, pytest 실행, 원격 트리 전체에서 grep 검색을 요청할 수 있습니다 — 서버는 SSH를 통해 통신하며, 경로 범위 제한과 명령 필터링을 적용합니다.

中文文档 / 중국어 버전 → · GitHub →

라이선스

MIT — LICENSE 참조.

Related MCP server: claude-ssh-mcp

기능

도구	용도
`ssh_read_file`	원격 파일 읽기
`ssh_write_file`	원격 파일 생성 또는 덮어쓰기 (추가도 가능)
`ssh_edit_file`	원격 파일 내에서 찾아 바꾸기
`ssh_list_directory`	권한, 크기, 수정 시간과 함께 원격 디렉터리 나열
`ssh_run_command`	원격에서 셸 명령 실행 (안전 필터 적용)
`ssh_search_files`	이름 glob 또는 내용으로 파일 찾기
`ssh_get_env_info`	OS / Python / 디스크 / 메모리 / CPU 스냅샷
`ssh_file_info`	단일 경로에 대한 상세 stat

빠른 시작

# 1. Clone and enter
git clone https://github.com/zhangqi-eiq/server_mcp.git
cd server_mcp

# 2. Install (editable mode — picks up code changes immediately)
python install.py

# 3. Edit your real credentials
#    (file is at ~/.ssh-mcp-server/config.json by default)

# 4. Restart Claude Code, then in a chat:
#    "show me the env of my server"

이것으로 끝입니다. install.py는 세 가지 작업을 수행합니다:

pip install -e . — 패키지를 설치합니다.
config.json(자리 표시자 값 포함)을 ~/.ssh-mcp-server/에 복사합니다.
claude mcp add를 실행하여 서버가 Claude Code에 표시되도록 합니다.

아직 claude CLI가 없다면 python install.py --no-register를 실행하고 MCP 항목을 직접 추가하세요 (수동 구성 참조).

수동 구성

직접 연결을 구성하거나 install.py가 올바르게 등록되지 않은 경우:

1. 패키지 설치

pip install -e .

이렇게 하면 ssh_mcp_server가 Python의 import 경로에 추가되어 python -m ssh_mcp_server로 서버를 실행할 수 있습니다.

2. 구성 파일 생성

config.json을 ~/.ssh-mcp-server/config.json에 복사하고(로더는 SSH_MCP_CONFIG가 설정되지 않았을 때 이 위치를 찾습니다) 실제 값을 입력하세요:

mkdir -p ~/.ssh-mcp-server
cp config.json ~/.ssh-mcp-server/config.json
$EDITOR ~/.ssh-mcp-server/config.json

3. Claude Code에 등록

MCP 항목은 설치한 Python 인터프리터를 통해 서버를 호출해야 합니다. 아래 <python>은 해당 인터프리터의 절대 경로여야 합니다(활성화된 환경의 sys.executable, 예: Windows의 C:\Users\you\.conda\envs\myenv\python.exe 또는 Linux의 /home/you/.venv/bin/python).

옵션 A — 사용자 범위, 모든 프로젝트에서 사용 가능:

claude mcp add --scope user ssh-remote \
  -e SSH_MCP_CONFIG="$HOME/.ssh-mcp-server/config.json" \
  -- "<python>" -m ssh_mcp_server

옵션 B — 프로젝트 범위, 이 프로젝트에서만:

프로젝트 루트에 .mcp.json을 생성하세요:

{
  "mcpServers": {
    "ssh-remote": {
      "command": "<absolute path to python>",
      "args": ["-m", "ssh_mcp_server"],
      "env": {
        "SSH_MCP_CONFIG": "/absolute/path/to/your/config.json"
      }
    }
  }
}

참고: Claude Code는 mcpServers를 두 곳에서 찾습니다 — ~/.claude.json (CLI 관리, claude mcp add로 작성) 및 ~/.claude/settings.json (수동 편집). 위의 CLI 경로는 자동으로 올바른 위치에 작성합니다.

구성 참조

config.json 형식:

{
  "ssh": {
    "host": "your-server.example.com",
    "port": 22,
    "username": "your-username",
    "auth": {
      "type": "password",
      "key_path": "",
      "password": "your-password",
      "key_password": ""
    },
    "connect_timeout": 10,
    "keepalive_interval": 30
  },
  "allowed_paths": [
    "/home/your-username/projects"
  ],
  "security": {
    "blocked_commands": ["rm -rf /", "mkfs", ...],
    "max_file_size_mb": 50,
    "max_output_chars": 100000,
    "command_timeout": 30
  }
}

SSH 연결

필드	설명	기본값
`ssh.host`	서버 주소 (IP 또는 도메인)	필수
`ssh.port`	SSH 포트	`22`
`ssh.username`	로그인 사용자 이름	필수
`ssh.auth.type`	`"key"` 또는 `"password"`	`"key"`
`ssh.auth.key_path`	개인 키 경로 (키 인증)	`type=key`인 경우 필수
`ssh.auth.password`	로그인 비밀번호 (비밀번호 인증)	`type=password`인 경우 필수
`ssh.auth.key_password`	키의 암호문	빈 값
`ssh.connect_timeout`	초 단위	`10`
`ssh.keepalive_interval`	keepalive 사이 초 단위	`30`

접근 제어

allowed_paths — 원격 디렉터리 화이트리스트. 모든 파일 작업은 .. 정규화 후 이 목록에 대해 검증됩니다. 목록에 없는 요청은 거부됩니다. 하위 경로는 접근을 상속합니다 (예: /data/proj는 /data/proj/sub/file.py를 허용).
security.blocked_commands — ssh_run_command가 실행을 거부하는 셸 명령 패턴 목록. 기본값은 명백한 위험 명령(rm -rf /, mkfs, shutdown, 포크 폭탄, 블록 장치에 대한 직접 쓰기)을 포함합니다. 목록을 확장할 수 있지만, 정당한 필요를 "해결"하기 위해 절대 약화하지 마세요 — 보안 모델 참조.

리소스 제한

필드	효과	기본값
`max_file_size_mb`	`ssh_read_file`이 이보다 큰 파일을 거부	`50`
`max_output_chars`	`ssh_run_command`가 이 문자 수를 초과하는 출력을 잘라냄	`100000`
`command_timeout`	`ssh_run_command`가 이 초 후 강제 종료	`30`

인증

키 기반 (권장)

# On your local machine
ssh-keygen -t ed25519 -C "you@example.com"

# Push the public key to the remote
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

그런 다음 config.json에서:

"auth": {
  "type": "key",
  "key_path": "~/.ssh/id_ed25519",
  "key_password": ""
}

key_password는 개인 키 자체가 암호화된 경우에만 필요합니다.

비밀번호 기반

"auth": {
  "type": "password",
  "password": "your-password"
}

비밀번호는 config.json에 평문으로 저장됩니다. 키 인증을 선호하세요.

GUI 관리자 (선택 사항)

작은 Tk 기반 GUI로 여러 서버 프로필을 유지 관리하고 전환할 수 있습니다:

# From source
python server_manager.py

# Or build a standalone Windows exe and put it on PATH
pip install -e ".[gui]"   # adds pyinstaller
python build.py
python setup_global.py
# now `SSH-Server-Manager` is on PATH

프로필은 profiles.json에 저장됩니다. 전환 시 선택한 프로필을 config.json에 복사하여 MCP 서버가 다음 실행 시 이를 사용하도록 합니다.

보안 모델

이 서버는 의도적으로 보수적입니다. 두 개의 독립적인 계층이 원격 호스트를 보호합니다:

경로 범위 제한. 모든 파일 작업은 정규화(.. 해석, 슬래시 병합)된 후 allowed_paths에 대해 검사됩니다. 목록을 벗어날 방법은 없습니다 — 검사는 원격에서 경로가 해석된 후 서버 측에서 수행됩니다.
명령 필터링. ssh_run_command는 security.blocked_commands(부분 문자열 일치)와 일치하는 모든 명령을 거부합니다. 기본 목록은 재귀적 삭제, 원시 장치 쓰기, 시스템 종료, 포크 폭탄, 원격 셸 설치 프로그램(curl … | sh)을 차단합니다. 특정 항목을 허용해야 한다면 목록을 확장하세요 — 그러나 무력화하지 마세요.

이 서버가 하지 않는 일:

원격에서 root로 실행되지 않습니다. 비-root 사용자로 SSH하세요.
sudo를 우회하지 않습니다. 구성된 사용자가 sudo를 할 수 없다면 서버도 할 수 없습니다.
대화형 셸을 제공하지 않습니다. 장기 실행 프로세스는 command_timeout에 의해 종료됩니다.

문제 해결

증상	가능한 원인	해결 방법
`claude mcp list`에 아무것도 표시되지 않음	서버가 잘못된 범위에 등록되었거나 `claude` CLI 버전이 `~/.claude/settings.json`을 읽지 못함	`claude mcp add --scope user ...` 사용 (`~/.claude.json`에 작성)
`ModuleNotFoundError: No module named 'mcp'`	`claude`가 사용하는 Python과 다른 Python에 설치됨	Claude Code가 사용할 인터프리터로 `install.py` 실행
`ERROR: ssh.host is required`	구성에 여전히 자리 표시자 값이 있음	`~/.ssh-mcp-server/config.json`을 편집하고 `your-server.example.com`, `CHANGE_ME` 등을 교체
`Access denied: outside allowed paths`	LLM이 시도한 경로가 `allowed_paths`에 없음	구성의 `allowed_paths`에 경로 추가
`Command blocked: dangerous pattern`	LLM이 차단 목록에 있는 명령을 시도함	정말 필요하다면 `security.blocked_commands` 조정
`SSH authentication failed`	잘못된 자격 증명 또는 잘못된 사용자	일반 셸에서 `ssh user@host`로 확인
서버가 시작되지만 Claude Code에 도구가 없음	오래된 VSCode 확장 프로세스	VSCode를 완전히 종료하고 다시 열기

프로젝트 구조

server/
├── ssh_mcp_server/         # MCP server package (the actual product)
│   ├── server.py           #   tool definitions
│   ├── ssh_client.py       #   paramiko wrapper
│   ├── security.py         #   path + command validation
│   └── config.py           #   config loader
├── server_manager.py       # Tk GUI for managing profiles
├── profiles.json           # GUI profile store
├── config.json             # runtime config template (placeholder values)
├── setup.py                # pip-installable package metadata
├── install.py              # one-shot installer (install + register)
├── setup_global.py         # optional: deploy GUI exe to PATH
├── build.py                # optional: PyInstaller wrapper for the GUI
├── SSH-Server-Manager.spec # PyInstaller spec for fine-grained builds
├── requirements.txt        # raw dependency pins
├── LICENSE                 # MIT
├── README.md               # this file (English)
└── README.zh.md            # Chinese translation

라이선스

MIT — 전체 텍스트는 파일을 참조하세요.

This server cannot be deployed

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

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Related MCP Connectors

Shellway A
com.getshellway
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Command Line Developer Tools Networking & Infrastructure
221
https://mcp.getshellway.com/mcp
BCD — Bridge Control Delegate A
com.snack-wrap.bcd
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
File Systems Command Line Browser Automation
751
https://bcd.snack-wrap.com/mcp
browser-ssh
com.browserssh
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Shell Access File Systems
2
https://api.browserssh.com/mcp
FreeRDC
io.github.danielarif26
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
File Systems
11
https://freerdc.sjaman.deno.net/mcp

Related MCP Servers

SSH Remote MCP Server
Shell Access Command Line OS Automation
nqmn
A
license
A
quality
D
maintenance
Enables SSH remote access to servers through Claude, allowing users to execute commands, transfer files via SFTP, and manage multiple remote connections using natural language.
Updated 4 months ago (2026-07-02 23:17 UTC)
12
9
MIT
claude-ssh-mcp
Shell Access File Systems Command Line
MaraBank
A
license
A
quality
C
maintenance
Enables Claude to connect to servers via SSH, execute commands, transfer files, and manage connections through natural language.
Updated 3 months ago (2026-07-25 07:06 UTC)
9
11 npm
1
MIT
MCP SSH Server
austinzq
-
license
Not graded
quality
Not graded
maintenance
Enables Claude Code to control remote servers via SSH for automated deployment, testing, and operations, including command execution and file transfer.
Updated a year ago (2025-06-23 15:11 UTC)
4
-
SSH MCP Server
Shell Access Command Line
quiloos39
A
license
Not graded
quality
F
maintenance
Enables Claude to execute commands on remote servers via SSH, with support for SSH config, private keys, password auth, and agent forwarding.
Updated 9 months ago (2026-02-16 11:17 UTC)
76 npm
ISC

SSH 원격 파일 MCP 서버

라이선스

기능

빠른 시작

수동 구성

1. 패키지 설치

2. 구성 파일 생성

3. Claude Code에 등록

구성 참조

SSH 연결

접근 제어

리소스 제한

인증

키 기반 (권장)

비밀번호 기반

GUI 관리자 (선택 사항)

보안 모델

문제 해결

프로젝트 구조

라이선스

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

SSH Remote MCP Server

claude-ssh-mcp

MCP SSH Server

SSH MCP Server